hecks 3.5.0 → 3.7.0

data/lib/hecks/quality_control/cli/qa_postgres_role.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pg"
+require_relative "qa_postgres_role/ownership"
 
 module Hecks
   module QualityControlCli
@@ -11,6 +12,8 @@ module Hecks
     #   hecks quality_control sweep.create_ledger_role <database> [--role <role>]   # role defaults
     # to hecks_qa
     class QaPostgresRole
+      include Ownership
+
       USAGE = "usage: hecks quality_control create_ledger_role <database> [--role <role>]"
 
       # `relkind` of each relation to the word `ALTER` takes for it. Partitions are their own
@@ -39,16 +42,39 @@ module Hecks
       # @return [Integer] the exit status
       # @raise [SystemExit] when the role is a superuser or `BYPASSRLS`, or the database is missing
       def call(argv)
-        argv = argv.dup
-        role = "hecks_qa"
-        if (index = argv.index("--role"))
-          role = argv[index + 1] or return usage("--role needs a name")
-          argv.slice!(index, 2)
-        end
+        database, role = parse(argv.dup)
+        provision(database, role)
+        0
+      rescue UsageError => e
+        usage(e.message)
+      end
+
+      private
+
+      # Raised for a wrong command line; `call` answers it with the usage line and status 1.
+      class UsageError < StandardError; end
+
+      def parse(argv)
+        role = take_role(argv)
         database = argv.shift
-        return usage("no database named") if database.to_s.empty?
-        return usage("unexpected argument #{argv.first.inspect}") unless argv.empty?
+        raise UsageError, "no database named" if database.to_s.empty?
+        raise UsageError, "unexpected argument #{argv.first.inspect}" unless argv.empty?
+
+        [database, role]
+      end
 
+      def take_role(argv)
+        index = argv.index("--role")
+        return "hecks_qa" unless index
+
+        role = argv[index + 1]
+        raise UsageError, "--role needs a name" unless role
+
+        argv.slice!(index, 2)
+        role
+      end
+
+      def provision(database, role)
         done = []
         skipped = []
         admin = PG.connect(dbname: "postgres")
@@ -57,11 +83,8 @@ module Hecks
         admin.close
         take_contents(database, role, done)
         report(database, role, done, skipped)
-        0
       end
 
-      private
-
       def usage(message)
         @err.puts "hecks quality_control create_ledger_role: #{message}"
         @err.puts USAGE
@@ -71,81 +94,53 @@ module Hecks
       def create_role(admin, role, done, skipped)
         attrs = admin.exec_params("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = $1", [role])
         if attrs.ntuples.zero?
-          # CREATE ROLE has no IF NOT EXISTS. Concurrent creates can lose on the catalog index
-          # (unique_violation) rather than duplicate_object, so the block rescues both.
-          admin.exec(<<~SQL)
-            DO $$ BEGIN
-              CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
-            EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
-            END $$
-          SQL
+          insert_role(admin, role)
           done << "created role #{role} (LOGIN, no SUPERUSER, no BYPASSRLS)"
         elsif attrs[0]["rolsuper"] == "t" || attrs[0]["rolbypassrls"] == "t"
-          admin.close
-          abort "hecks quality_control create_ledger_role: role #{role} already exists as " \
-                "#{attrs[0]['rolsuper'] == 't' ? 'a superuser' : 'a BYPASSRLS role'} — the era write-fence " \
-                "cannot bite it, which is the exact state this script exists to end. Pick another role, or " \
-                "ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
+          refuse_privileged_role(admin, role, attrs[0])
         else
           skipped << "role #{role} exists, ordinary"
         end
       end
 
+      # CREATE ROLE has no IF NOT EXISTS. Concurrent creates can lose on the catalog index
+      # (unique_violation) rather than duplicate_object, so the block rescues both.
+      def insert_role(admin, role)
+        admin.exec(<<~SQL)
+          DO $$ BEGIN
+            CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
+          EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+          END $$
+        SQL
+      end
+
+      def refuse_privileged_role(admin, role, attrs)
+        admin.close
+        abort "hecks quality_control create_ledger_role: role #{role} already exists as " \
+              "#{attrs["rolsuper"] == "t" ? "a superuser" : "a BYPASSRLS role"} — the era write-fence " \
+              "cannot bite it, which is the exact state this script exists to end. Pick another role, or " \
+              "ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
+      end
+
       def take_database(admin, database, role, done, skipped)
-        owner = admin.exec_params(
-          "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
-        )
-        if owner.ntuples.zero?
-          admin.close
-          abort "hecks quality_control create_ledger_role: no database #{database} — createdb it first (PostgresEra provisions " \
-                "every table it needs on first connect, never the database itself)"
-        end
-        if owner[0]["owner"] == role
+        owner = database_owner(admin, database)
+        if owner == role
           skipped << "database #{database} already owned by #{role}"
         else
           admin.exec("ALTER DATABASE #{admin.quote_ident(database)} OWNER TO #{admin.quote_ident(role)}")
-          done << "database #{database}: owner #{owner[0]['owner']} -> #{role}"
-        end
-      end
-
-      def take_contents(database, role, done)
-        db = PG.connect(dbname: database)
-        quoted_role = db.quote_ident(role)
-        schema_owner = db.exec("SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = 'public'")
-        if schema_owner.ntuples.positive? && schema_owner[0]["owner"] != role
-          db.exec("ALTER SCHEMA public OWNER TO #{quoted_role}")
-          done << "schema public: owner #{schema_owner[0]['owner']} -> #{role}"
+          done << "database #{database}: owner #{owner} -> #{role}"
         end
-        take_relations(db, role, quoted_role, done)
-        take_functions(db, role, quoted_role, done)
-        db.close
       end
 
-      # relkind: r table, p partitioned table, S sequence, v view, m matview.
-      def take_relations(db, role, quoted_role, done)
-        relations = db.exec_params(<<~SQL, [role])
-          SELECT c.relname, c.relkind, pg_get_userbyid(c.relowner) AS owner
-          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
-          WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND pg_get_userbyid(c.relowner) <> $1
-          ORDER BY c.relkind, c.relname
-        SQL
-        relations.each do |row|
-          db.exec("ALTER #{KINDS.fetch(row['relkind'])} #{db.quote_ident(row['relname'])} OWNER TO #{quoted_role}")
-        end
-        done << "#{relations.ntuples} relation(s) in public -> #{role}" if relations.ntuples.positive?
-      end
+      def database_owner(admin, database)
+        rows = admin.exec_params(
+          "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
+        )
+        return rows[0]["owner"] unless rows.ntuples.zero?
 
-      def take_functions(db, role, quoted_role, done)
-        functions = db.exec_params(<<~SQL, [role])
-          SELECT p.proname, pg_get_function_identity_arguments(p.oid) AS args
-          FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
-          WHERE n.nspname = 'public' AND pg_get_userbyid(p.proowner) <> $1
-          ORDER BY p.proname
-        SQL
-        functions.each do |row|
-          db.exec("ALTER FUNCTION #{db.quote_ident(row['proname'])}(#{row['args']}) OWNER TO #{quoted_role}")
-        end
-        done << "#{functions.ntuples} function(s) in public -> #{role}" if functions.ntuples.positive?
+        admin.close
+        abort "hecks quality_control create_ledger_role: no database #{database} — createdb it first (PostgresEra provisions " \
+              "every table it needs on first connect, never the database itself)"
       end
 
       def report(database, role, done, skipped)

data/lib/hecks/quality_control/cli/qa_pr_check/checking.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaPrCheck
+      # What `clearance.check_pull_requests` does with one tracked PR: retire it when GitHub says it
+      # is settled, skip it while checks run, otherwise ask the ledger for a verdict on its head.
+      module Checking
+        # The `gh` state of a settled PR to the ledger command that retires it and what to say.
+        RETIREMENTS = { "MERGED" => ["Merge", "merged"], "CLOSED" => ["Close", "closed without merging"] }.freeze
+
+        # One tracked PR as the checks see it: its worklist aggregate, number and display label, the
+        # bug or angle it cites, and the live head sha.
+        Pull = Struct.new(:aggregate, :number, :label, :citation, :sha) do
+          # @return [String] the prefix every line about this PR starts with
+          def tag
+            "#{label}, #{citation}, #{sha[0, 7]}"
+          end
+
+          # @param summary [String] what the CI port said about the red head
+          # @return [Hash] the newly-red record the report prints
+          def finding(summary)
+            { aggregate: aggregate, pr: number, citation: citation, commit: sha, refusal: summary }
+          end
+        end
+
+        private
+
+        # Checks one tracked PR, appending to `@newly_red` or `@operational_errors`. The live head
+        # sha is read from gh each run, since a push mints a new commit to clear.
+        def check_one_pr(row, aggregate:, citation_field:, citation_label:)
+          number = field(row, :number, :value)
+          label = "#{aggregate} PR ##{number} (#{field(row, :branch, :value)})"
+          view = reading_gh(label) { @git_pr.pull_request(number) }
+          return unless view
+          return if retire_if_settled?(view, number, label, aggregate)
+
+          sha = view[:headRefOid].to_s
+          return reject_sha(label, sha) unless sha.match?(SHA_PATTERN)
+
+          citation = citation_for(row, citation_field, citation_label)
+          check_clearance(Pull.new(aggregate, number, label, citation, sha))
+        end
+
+        def reject_sha(label, sha)
+          @operational_errors << "#{label}: head commit #{sha.inspect} does not look like a sha — skipping"
+        end
+
+        def citation_for(row, citation_field, citation_label)
+          cited = field(row, citation_field)
+          cited ? "#{citation_label} #{cited}" : "no #{citation_label} cited"
+        end
+
+        def check_clearance(pull)
+          existing = clearance_for_commit(pull.sha)
+          return puts("#{pull.tag}: already cleared (#{existing[:status]}) — settled once, not re-checked") if existing
+          return unless checks_settled?(pull)
+
+          ask_the_ledger(pull)
+        end
+
+        def clearance_for_commit(sha)
+          query("Clearance.All").find { |row| field(row, :commit, :value) == sha }
+        end
+
+        # Retires a Patch/Improvement whose PR GitHub reports merged or closed; nothing else tells
+        # the ledger. Returns true if it retired one.
+        def retire_if_settled?(view, number, label, aggregate)
+          verb, outcome = RETIREMENTS[view[:state]]
+          return false unless verb
+
+          @runtime.dispatch_flat("QualityControl::#{aggregate}.#{verb}", { id: number })
+          puts "#{label}: #{outcome} — retired from the worklist"
+          true
+        end
+
+        # Runs a read against `gh`; a failure is appended to `@operational_errors` and answers nil.
+        def reading_gh(label)
+          yield
+        rescue Hecks::Adapters::GitPr::CommandFailed => e
+          @operational_errors << "#{label}: #{e.message}"
+          nil
+        end
+
+        # True when every check has finished, so a verdict is worth asking for. Pending stays out
+        # here because the CI port cannot express "ask again later".
+        def checks_settled?(pull)
+          checks = reading_gh(pull.label) { @git_pr.checks(pull.number) }
+          return false unless checks
+
+          reason = unsettled_reason(checks)
+          puts "#{pull.tag}: #{reason} — skipping this run" if reason
+          reason.nil?
+        end
+
+        def unsettled_reason(checks)
+          return "gh reports no checks at all yet" if checks.empty?
+
+          "checks still running" if checks.any? { |c| c[:bucket] == "pending" }
+        end
+
+        # Starts a Clearance and asks the CI port for a verdict. ClearOnPass/RefuseOnFail settle
+        # the record synchronously, so `find` sees it straight away; a red one is appended to
+        # `@newly_red`.
+        def ask_the_ledger(pull)
+          ::QualityControl::Clearance.start!(commit: { value: pull.sha })
+          @runtime.dispatch_flat("QualityControl::Clearance.CI.Run", { commit: pull.sha })
+          cleared = ::QualityControl::Clearance.find(pull.sha)
+          summary = cleared.summary.to_h[:value]
+          return puts("#{pull.tag}: CLEARED — #{summary}") if cleared.status == "green"
+
+          puts "#{pull.tag}: RED — #{summary}"
+          @newly_red << pull.finding(summary)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_pr_check/reporting.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaPrCheck
+      # What `clearance.check_pull_requests` prints once every tracked PR was looked at.
+      module Reporting
+        private
+
+        def report_errors
+          return if @operational_errors.empty?
+
+          puts
+          puts "operational error(s):"
+          @operational_errors.each { |message| puts "  #{message}" }
+        end
+
+        def report_clean
+          puts
+          puts "clean — every PR QualityControl::Patch or QualityControl::Improvement tracks as open is " \
+               "either already cleared, still running, or was retired this run."
+          EXIT_OK
+        end
+
+        def report_newly_red
+          print_newly_red_header
+          @newly_red.each { |finding| print_finding(finding) }
+          EXIT_NEWLY_RED
+        end
+
+        def print_newly_red_header
+          puts
+          puts "=" * 72
+          puts "FOUND #{@newly_red.length} NEWLY-RED PR(S) — BugCiWatch/ImprovementCiWatch already dispatched " \
+               "the matching Regress for each, by aggregate."
+          puts "An agent picks up the investigation from here: the same judgment"
+          puts "SKILL.md's own \"on a surprising check\" section describes for a sweep's"
+          puts "own find — self-contained fix with a regression test and a draft PR,"
+          puts "or leave the record for something bigger. Never re-verify from this script."
+          puts "=" * 72
+        end
+
+        def print_finding(finding)
+          puts
+          puts "aggregate: #{finding[:aggregate]}"
+          puts "citation:  #{finding[:citation]}"
+          puts "pr:        ##{finding[:pr]}"
+          puts "commit:    #{finding[:commit]}"
+          puts "refusal:   #{finding[:refusal]}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_pr_check.rb

@@ -4,6 +4,8 @@ require_relative "../../../hecks"
 # The ledger's `persisted_by "PostgresEra"` binding needs the era plugin, which core does not load.
 require_relative "../../ports/persistence/plugins/era"
 require_relative "../adapters/git_pr"
+require_relative "qa_pr_check/checking"
+require_relative "qa_pr_check/reporting"
 
 module Hecks
   module QualityControlCli
@@ -15,6 +17,9 @@ module Hecks
     # 2 a newly red PR, with the details on stdout. A commit's `Clearance` is minted once and never
     # re-asked; pending checks are skipped, since the CI port has no way to say "ask again later".
     class QaPrCheck
+      include Checking
+      include Reporting
+
       EXIT_OK = 0
       EXIT_ERROR = 1
       EXIT_NEWLY_RED = 2
@@ -51,30 +56,34 @@ module Hecks
       # @return [Integer] the exit status
       # @raise [SystemExit] when given arguments, or the ledger does not boot
       def call(argv)
-        unless argv.empty?
-          if %w[-h --help].include?(argv.first)
-            puts USAGE
-            return EXIT_OK
-          end
-          abort "#{USAGE}\nthis script takes no arguments — it checks every PR QualityControl::Patch or " \
-                "QualityControl::Improvement tracks as open, every time"
-        end
+        return reject_arguments(argv) unless argv.empty?
 
         # Every `gh` call goes through the `GitPr` adapter. With `--json`, gh exits 0 whatever the
         # checks say, so a failure means only that the call did not succeed.
         @git_pr = Hecks::Adapters::GitPr.new(repo_dir: Dir.pwd)
         @runtime = boot_ledger
         worklists = WORKLISTS.to_h { |w| [w, query("#{w[:aggregate]}.Open")] }
-        if worklists.values.all?(&:empty?)
-          puts "no PRs tracked as open by QualityControl::Patch or QualityControl::Improvement — nothing to check"
-          return EXIT_OK
-        end
+        return nothing_to_check if worklists.values.all?(&:empty?)
 
         check_all(worklists)
       end
 
       private
 
+      def reject_arguments(argv)
+        if %w[-h --help].include?(argv.first)
+          puts USAGE
+          return EXIT_OK
+        end
+        abort "#{USAGE}\nthis script takes no arguments — it checks every PR QualityControl::Patch or " \
+              "QualityControl::Improvement tracks as open, every time"
+      end
+
+      def nothing_to_check
+        puts "no PRs tracked as open by QualityControl::Patch or QualityControl::Improvement — nothing to check"
+        EXIT_OK
+      end
+
       def boot_ledger
         Hecks.boot(@domain_dir)
       rescue StandardError => e
@@ -83,19 +92,16 @@ module Hecks
       end
 
       def check_all(worklists)
-        newly_red = []
-        operational_errors = []
+        @newly_red = []
+        @operational_errors = []
         worklists.each do |worklist, rows|
-          rows.each { |row| check_one_pr(row, newly_red, operational_errors, **worklist) }
+          rows.each { |row| check_one_pr(row, **worklist) }
         end
-        report_errors(operational_errors)
-        return report_newly_red(newly_red) if newly_red.any?
-        return EXIT_ERROR if operational_errors.any?
+        report_errors
+        return report_newly_red if @newly_red.any?
+        return EXIT_ERROR if @operational_errors.any?
 
-        puts
-        puts "clean — every PR QualityControl::Patch or QualityControl::Improvement tracks as open is " \
-             "either already cleared, still running, or was retired this run."
-        EXIT_OK
+        report_clean
       end
 
       def query(name, **args) = @runtime.query("QualityControl::#{name}", **args)
@@ -104,129 +110,6 @@ module Hecks
       def field(row, *path)
         path.reduce(row) { |held, key| held.nil? ? nil : held[key] }
       end
-
-      def clearance_for_commit(sha)
-        query("Clearance.All").find { |row| field(row, :commit, :value) == sha }
-      end
-
-      # Retires a Patch/Improvement whose PR GitHub reports merged or closed; nothing else tells
-      # the ledger. Returns true if it retired one.
-      def retire_if_settled?(view, number, label, aggregate)
-        case view[:state]
-        when "MERGED"
-          @runtime.dispatch_flat("QualityControl::#{aggregate}.Merge", { id: number })
-          puts "#{label}: merged — retired from the worklist"
-          true
-        when "CLOSED"
-          @runtime.dispatch_flat("QualityControl::#{aggregate}.Close", { id: number })
-          puts "#{label}: closed without merging — retired from the worklist"
-          true
-        else
-          false
-        end
-      end
-
-      # Runs a read against `gh`; a failure is appended to `operational_errors` and answers nil.
-      def reading_gh(label, operational_errors)
-        yield
-      rescue Hecks::Adapters::GitPr::CommandFailed => e
-        operational_errors << "#{label}: #{e.message}"
-        nil
-      end
-
-      # True when every check has finished, so a verdict is worth asking for. Pending stays out
-      # here because the CI port cannot express "ask again later".
-      def checks_settled?(number, label, citation, sha, operational_errors)
-        checks = reading_gh(label, operational_errors) { @git_pr.checks(number) }
-        return false unless checks
-
-        if checks.empty?
-          puts "#{label}, #{citation}, #{sha[0, 7]}: gh reports no checks at all yet — skipping this run"
-          return false
-        end
-
-        if checks.any? { |c| c[:bucket] == "pending" }
-          puts "#{label}, #{citation}, #{sha[0, 7]}: checks still running — skipping this run"
-          return false
-        end
-
-        true
-      end
-
-      # Checks one tracked PR, appending to `newly_red` or `operational_errors` in place. The live
-      # head sha is read from gh each run, since a push mints a new commit to clear.
-      def check_one_pr(row, newly_red, operational_errors, aggregate:, citation_field:, citation_label:)
-        number = field(row, :number, :value)
-        cited = field(row, citation_field)
-        citation = cited ? "#{citation_label} #{cited}" : "no #{citation_label} cited"
-        label = "#{aggregate} PR ##{number} (#{field(row, :branch, :value)})"
-
-        view = reading_gh(label, operational_errors) { @git_pr.pull_request(number) }
-        return unless view
-        return if retire_if_settled?(view, number, label, aggregate)
-
-        sha = view[:headRefOid].to_s
-        unless sha.match?(SHA_PATTERN)
-          operational_errors << "#{label}: head commit #{sha.inspect} does not look like a sha — skipping"
-          return
-        end
-
-        if (existing = clearance_for_commit(sha))
-          puts "#{label}, #{citation}, #{sha[0, 7]}: already cleared (#{existing[:status]}) — " \
-               "settled once, not re-checked"
-          return
-        end
-        return unless checks_settled?(number, label, citation, sha, operational_errors)
-
-        ask_the_ledger(sha, label, citation, number, newly_red, aggregate: aggregate)
-      end
-
-      # Starts a Clearance and asks the CI port for a verdict. ClearOnPass/RefuseOnFail settle the
-      # record synchronously, so `find` sees it straight away; a red one is appended to `newly_red`.
-      def ask_the_ledger(sha, label, citation, number, newly_red, aggregate:)
-        ::QualityControl::Clearance.start!(commit: { value: sha })
-        @runtime.dispatch_flat("QualityControl::Clearance.CI.Run", { commit: sha })
-
-        cleared = ::QualityControl::Clearance.find(sha)
-        summary = cleared.summary.to_h[:value]
-
-        if cleared.status == "green"
-          puts "#{label}, #{citation}, #{sha[0, 7]}: CLEARED — #{summary}"
-          return
-        end
-
-        puts "#{label}, #{citation}, #{sha[0, 7]}: RED — #{summary}"
-        newly_red << { aggregate: aggregate, pr: number, citation: citation, commit: sha, refusal: summary }
-      end
-
-      def report_errors(operational_errors)
-        return if operational_errors.empty?
-
-        puts
-        puts "operational error(s):"
-        operational_errors.each { |message| puts "  #{message}" }
-      end
-
-      def report_newly_red(newly_red)
-        puts
-        puts "=" * 72
-        puts "FOUND #{newly_red.length} NEWLY-RED PR(S) — BugCiWatch/ImprovementCiWatch already dispatched " \
-             "the matching Regress for each, by aggregate."
-        puts "An agent picks up the investigation from here: the same judgment"
-        puts "SKILL.md's own \"on a surprising check\" section describes for a sweep's"
-        puts "own find — self-contained fix with a regression test and a draft PR,"
-        puts "or leave the record for something bigger. Never re-verify from this script."
-        puts "=" * 72
-        newly_red.each do |finding|
-          puts
-          puts "aggregate: #{finding[:aggregate]}"
-          puts "citation:  #{finding[:citation]}"
-          puts "pr:        ##{finding[:pr]}"
-          puts "commit:    #{finding[:commit]}"
-          puts "refusal:   #{finding[:refusal]}"
-        end
-        EXIT_NEWLY_RED
-      end
     end
   end
 end

data/lib/hecks/quality_control/cli/qa_seed_angles/seed.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaSeedAngles
+      # A `resolution:` present means the lead was already chased down: it is proposed,
+      # investigated and built in one pass. Its absence means the lever is still open.
+      SEED = [
+        {
+          reference:  "ANGLE-1",
+          premise:    "None of BUG#1-5 touched saga/process_manager machinery at all, despite this " \
+                      "session having just built a real one (BugCiWatch) — a stress domain specifically " \
+                      "exercising process-manager correlation, multi-step handler chains, and compensation " \
+                      "legs was a natural, and the highest-priority, next target.",
+          citation:   "BugCiWatch (lib/hecks/quality_control/quality_control.bluebook, \"noticing when a fix " \
+                      "stops holding\"); BUG#1-5, none of which touched saga machinery",
+          proposer:   "Claude QA",
+          resolution: "BUG#6 — SagaInterpreter#qualified cannot tell a same-domain nested-entity " \
+                      "command reference (dispatch Manifest::Slot::Fill) apart from a genuine " \
+                      "cross-domain qualifier, so the leg is silently read as targeting a nonexistent " \
+                      "domain and refuses every time; found by qa/stress_domains/waybill on its first " \
+                      "real run, before fuzzing was even needed. PR #530 (merged)."
+        },
+        {
+          reference: "ANGLE-2",
+          premise:   "nested_pieces (qa/stress_domains/nested_pieces) proves two-level ENTITY nesting " \
+                     "fuzzes and dispatches correctly, but nothing in the corpus exercises deep " \
+                     "reference_to HOPS — a chain of reference-typed lookups across aggregates — or a " \
+                     "governance/authorization-shaped construct combined with existence-checking. Entity " \
+                     "nesting and reference hopping are different DSL mechanisms entirely (entity " \
+                     "addressing vs CommandRules::References#resolve_references / " \
+                     "resolve_state_references), and ADR 0037's own Finding 5 already shows reference " \
+                     "resolution is exactly the kind of place Ruby and Rust structurally diverge — a " \
+                     "stress domain built around multi-hop references, or a scope/authorization check " \
+                     "combined with existence-checking, is a genuinely different construct combination " \
+                     "from anything the six bugs found this session actually touched.",
+          citation:  "qa/stress_domains/nested_pieces (entity nesting, not reference hops); " \
+                     "docs/decisions/0037-generated-sequence-fuzz-bridge-found-real-gaps-two-fixed-" \
+                     "three-catalogued.md, Finding 5 (resolve_state_references never ported to Rust)",
+          proposer:  "Claude QA"
+        },
+        {
+          reference: "ANGLE-3",
+          premise:   "BUG#1/#3/#4 were specifically ENGINE-DIVERGENCE bugs — Ruby and Rust disagreeing " \
+                     "on the same dispatch — a class Ruby-only property/exception fuzzing structurally " \
+                     "cannot see, because there is no second engine to disagree with. " \
+                     "spec/rust_conformance_fuzz_spec.rb's own DOMAINS list wires up only pizzas and " \
+                     "banking for CI-gated differential fuzzing. rust/Cargo.toml already declares " \
+                     "compiled-binary features for compliance and roster (plus meta) that " \
+                     "sit unused for this purpose; examples/chess and examples/directory have no Cargo " \
+                     "feature at all — `hecks project_rust` has never regenerated a binary for either. " \
+                     "Widening either list would let differential fuzzing catch a whole bug class " \
+                     "Ruby-only fuzzing cannot, on domains the practice already owns.",
+          citation:  "BUG#1/#3/#4 (engine-divergence bugs); spec/rust_conformance_fuzz_spec.rb DOMAINS " \
+                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/" \
+                     "meta have binaries and are not wired in; chess/directory have no feature at all)",
+          proposer:  "Claude QA"
+        },
+        {
+          reference: "ANGLE-4",
+          premise:   "lib/hecks/bluebook/model_check.rb's ALLOWED_FINDINGS, " \
+                     "spec/fuzzing/meta_domain_coverage_spec.rb's META_DOMAIN_GUARANTEED_BY_CONSTRUCTION " \
+                     "and META_DOMAIN_KNOWN_GAPS, and ADR 0037's own catalogued Findings 3-5 are all " \
+                     "places where something once labeled 'known, not a bug' could be re-examined — a " \
+                     "gap accepted a year ago is not guaranteed to still be the right call once the " \
+                     "surrounding code has moved. This session's own waybill finding (BUG#6) confirmed a " \
+                     "SECOND instance of exactly the family ALLOWED_FINDINGS[\"quality_control\"] already " \
+                     "named once (Naming.command_ref's bare-constant rewrite conflating a genuine " \
+                     "cross-domain qualifier with mere nesting) — proof the allowlists are themselves a " \
+                     "live source of leads, not just a static ledger of settled questions.",
+          citation:  "lib/hecks/bluebook/model_check.rb ALLOWED_FINDINGS; " \
+                     "spec/fuzzing/meta_domain_coverage_spec.rb META_DOMAIN_GUARANTEED_BY_CONSTRUCTION / " \
+                     "META_DOMAIN_KNOWN_GAPS; docs/decisions/0037-generated-sequence-fuzz-bridge-found-" \
+                     "real-gaps-two-fixed-three-catalogued.md Findings 3-5",
+          proposer:  "Claude QA"
+        }
+      ].freeze
+    end
+  end
+end