hecks 2.9.0 → 3.0.0

data/lib/hecks/quality_control/adapters/agent.adapter

@@ -0,0 +1,7 @@
+# Binds the `Agent` port to `Agent`; `hecks quality_control mine_combinations` asks it to write candidate domains.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/agent"
+
+Hecks.adapter "Agent" do
+  port "Agent"
+end

data/lib/hecks/quality_control/adapters/agent.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module Hecks
+  module Adapters
+    # The `Agent` port's adapter: hands a prompt to an agent on the command line and lets it work
+    # in the checkout, the way `hecks quality_control mine_combinations` asks one for candidate
+    # domains.
+    #
+    # Not the interviewer behind the framework's `agent` port (`ClaudeCode`), which reads one
+    # JSON answer back: this agent edits files, so the only answer is whether it finished.
+    class Agent
+      # An agent that could not start, or ended with a failure.
+      class Failed < StandardError; end
+
+      # The command run when neither the caller nor `QA_MINER_AGENT` names one.
+      DEFAULT_COMMAND = ["claude", "-p", "--permission-mode", "acceptEdits",
+                         "--allowedTools", "Read,Glob,Grep,Write,Edit"].freeze
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # The command an ask runs.
+      #
+      # @param command [String, Array<String>, nil] a command line, or its words
+      # @return [Array<String>] `command` as words; `QA_MINER_AGENT` else `DEFAULT_COMMAND` when nil
+      def command_for(command = nil)
+        command ||= ENV.fetch("QA_MINER_AGENT", nil)
+        return DEFAULT_COMMAND unless command
+
+        command.is_a?(String) ? Shellwords.split(command) : command
+      end
+
+      # Runs the agent with `prompt` on its standard input.
+      #
+      # @param prompt [String] what the agent is asked to do
+      # @param command [String, Array<String>, nil] the agent's command; see `command_for`
+      # @param chdir [String] the directory the agent works in
+      # @param log [String, nil] a file the agent's output is appended to
+      # @return [String] the agent's output
+      # @raise [Failed] when the agent cannot start or exits non-zero
+      def ask(prompt:, chdir:, command: nil, log: nil)
+        words = command_for(command)
+        output, status = Open3.capture2e(*words, stdin_data: prompt, chdir: chdir)
+        File.open(log, "a") { |file| file.puts(output) } if log
+        return output if status.success?
+
+        raise Failed, "agent exited #{status.exitstatus}: #{output.lines.last(5).join.strip}"
+      rescue SystemCallError => e
+        raise Failed, "agent could not start (#{words.first}): #{e.message}"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/angle_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `AngleTools` port to `AngleTools`, which answers `Angle`'s query: the seed of the backlog.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/angle_tools"
+
+Hecks.adapter "AngleTools" do
+  port "AngleTools"
+end

data/lib/hecks/quality_control/adapters/angle_tools.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `AngleTools` port's adapter: answers `Angle`'s query by running the seed of the backlog.
+    class AngleTools < QaTool
+      # @return [Hash] `text:` each starting lead's outcome: proposed, or already on file
+      def seed
+        run_command("qa_seed_angles")
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/clearance_recorder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QA
+    # Records what CI said about one commit as a `QualityControl::Clearance`.
+    module ClearanceRecorder
+      module_function
+
+      # Conclusions that count as green; same vocabulary as `GithubChecks::PASSING`.
+      # A `check_suite` conclusion aggregates one GitHub App's runs only, so callers decide
+      # which suites may pass a commit.
+      PASSING = %w[success neutral skipped].freeze
+
+      # Returns the Clearance for `commit`, starting one if none exists.
+      # `AlreadyExists` from a redelivered webhook racing another start is swallowed.
+      def ensure_started(commit)
+        QualityControl::Clearance.find(commit) ||
+          QualityControl::Clearance.start!(commit: { value: commit })
+      rescue Hecks::Runtime::AlreadyExists
+        QualityControl::Clearance.find(commit)
+      end
+
+      # Starts and settles the Clearance for `commit`; the first verdict recorded stands.
+      # An already-settled record is returned unchanged, so redelivery cannot raise
+      # `LifecycleRefused`.
+      #
+      # @return the settled Clearance
+      def record(commit:, passed:, summary:)
+        cleared = ensure_started(commit)
+        return cleared if cleared.status != "running"
+
+        passed ? cleared.passed!(summary: { value: summary }) : cleared.failed!(refusal: { value: summary })
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/clearance_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `ClearanceTools` port to `ClearanceTools`, which answers `Clearance`'s query: the PR check.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/clearance_tools"
+
+Hecks.adapter "ClearanceTools" do
+  port "ClearanceTools"
+end

data/lib/hecks/quality_control/adapters/clearance_tools.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `ClearanceTools` port's adapter: answers `Clearance`'s query by running the PR check. A
+    # newly red PR ends the check with status 2, which is an answer; anything else it calls an
+    # error is refused with its report.
+    class ClearanceTools < QaTool
+      # @return [Hash] `text:` what the check found for each open PR the ledger tracks
+      def check_pull_requests
+        run_command("qa_pr_check", answers: [0, 2])
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/git_pr.adapter

@@ -0,0 +1,7 @@
+# Binds the `GitPr` port to `GitPr`; the ledger's scripts ask it for every `git` and `gh` call.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/git_pr"
+
+Hecks.adapter "GitPr" do
+  port "GitPr"
+end

data/lib/hecks/quality_control/adapters/git_pr.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `GitPr` port's adapter: the `git` and `gh` calls behind a pull request the QA practice
+    # opens or checks, and the two rules that need the outside world to answer.
+    #
+    # The rules a ledger record can answer (the branch prefix, the bug being fixed, the angle
+    # being under investigation) are `given`s on `Patch.Open` and `Improvement.Open`. The two
+    # here need the repository or a count of today's pull requests: the per-day cap and the fix
+    # commit being an ancestor of `HEAD`.
+    class GitPr
+      # A rule the adapter enforces refused the request; nothing was opened.
+      class Refusal < StandardError; end
+
+      # `git` or `gh` could not do what was asked, whatever the request.
+      class CommandFailed < StandardError; end
+
+      # A commit sha as it may be handed to `git` as a revision.
+      SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+      # The remote a branch is pushed to and `gh pr create --head` reads it from.
+      REMOTE = "origin"
+
+      # What `gh pr view` says when the branch simply has no pull request.
+      NO_PR = /no pull requests? found/i
+
+      # The fields `gh pr view` is asked for when a PR is opened or looked up by branch.
+      VIEW_FIELDS = "number,url,headRefName,headRefOid,title,state"
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      # @param repo_dir [String] the checkout `git` and `gh` run in; `QA_REPO_DIR` picks one so a
+      #   spec can use a throwaway repository and a fake `gh`
+      def initialize(aggregate: nil, settings: {}, root: nil, repo_dir: ENV.fetch("QA_REPO_DIR", Dir.pwd))
+        @repo_dir = repo_dir
+      end
+
+      # @return [String] the checkout's current branch
+      # @raise [Refusal] when the directory is not a git checkout
+      def branch
+        out, _err, status = git("rev-parse", "--abbrev-ref", "HEAD")
+        raise Refusal, "not a git checkout at #{@repo_dir}" unless status.success?
+
+        out
+      end
+
+      # @return [String] the commit `HEAD` names
+      def head = git("rev-parse", "HEAD").first
+
+      # Refuses a checkout with uncommitted work, since a PR opened from it would not carry it.
+      #
+      # @return [void]
+      # @raise [Refusal] when `git status` cannot be read or reports changes
+      def assert_clean_tree!
+        dirty, _err, status = git("status", "--porcelain")
+        raise Refusal, "could not read git status at #{@repo_dir}" unless status.success?
+        return if dirty.empty?
+
+        raise Refusal, "the working tree at #{@repo_dir} is dirty — commit or discard first:\n#{dirty}"
+      end
+
+      # Refuses one more pull request than the day's cap allows; a cap of zero is no cap.
+      #
+      # @param opened_today [Integer] how many PRs the ledger recorded since local midnight
+      # @param cap [Integer] `PR_CAP_PER_DAY`
+      # @return [void]
+      # @raise [Refusal] when `opened_today` has reached a positive `cap`
+      def assert_under_daily_cap!(opened_today:, cap:)
+        return unless cap.positive? && opened_today >= cap
+
+        raise Refusal, "#{opened_today} PR(s) already opened since local midnight, and " \
+                       "QualityControlDials::PR_CAP_PER_DAY is #{cap} — leave this as an open Bug/Angle " \
+                       "and open it tomorrow, or raise the dial in qa/settings.yml"
+      end
+
+      # Refuses a fix commit that is not part of the branch being opened.
+      #
+      # @param commit [String] the commit the ledger says fixes the bug
+      # @param owner [String] what the commit belongs to, worded into the refusal (`"BUG#1"`)
+      # @return [void]
+      # @raise [Refusal] when `commit` is not a sha or not an ancestor of `HEAD`
+      def assert_ancestor!(commit:, owner:)
+        assert_sha!(commit, owner)
+        _out, _err, status = git("merge-base", "--is-ancestor", "--", commit, "HEAD")
+        return if status.success?
+
+        raise Refusal, "#{owner}'s own fix commit #{commit[0, 7]} is not an ancestor of HEAD " \
+                       "(#{head[0, 7]}) on #{branch} — the PR must carry the commit the ledger says fixes it"
+      end
+
+      # Refuses a fix commit that the pushed branch does not carry: `gh pr create --head` opens
+      # the pull request from the remote branch, not from the local checkout.
+      #
+      # @param branch [String] the head branch
+      # @param commit [String] the commit the ledger says fixes the bug
+      # @param owner [String] what the commit belongs to, worded into the refusal
+      # @return [void]
+      # @raise [Refusal] when the branch is not on the remote, or its tip does not carry `commit`
+      def assert_pushed!(branch:, commit:, owner:)
+        assert_sha!(commit, owner)
+        out, err, status = git("ls-remote", "--heads", REMOTE, "refs/heads/#{branch}")
+        raise Refusal, "could not read #{REMOTE} for #{branch}: #{err}" unless status.success?
+
+        tip = out.split.first.to_s
+        raise Refusal, "#{branch} is not pushed to #{REMOTE} — push it before opening the PR" if tip.empty?
+
+        assert_carries!(tip, commit, owner, "the pushed #{REMOTE}/#{branch}")
+      end
+
+      # Refuses a pull request whose head does not carry the fix commit.
+      #
+      # @param head [String] the PR's head commit, as `gh` reports it
+      # @param commit [String] the commit the ledger says fixes the bug
+      # @param owner [String] what the commit belongs to, worded into the refusal
+      # @return [void]
+      # @raise [Refusal] when `head` is not a sha, or does not carry `commit`
+      def assert_pr_head!(head:, commit:, owner:)
+        assert_sha!(commit, owner)
+        assert_sha!(head, "the PR head")
+        assert_carries!(head, commit, owner, "the PR head")
+      end
+
+      # The open PR for a branch.
+      #
+      # @param branch [String] the head branch
+      # @return [Hash{Symbol => Object}, nil] `gh pr view`'s fields, or nil when no PR is open
+      # @raise [CommandFailed] when `gh` failed for any reason but the branch having no PR
+      def open_pull_request(branch)
+        out, err, status = gh("pr", "view", branch, "--json", VIEW_FIELDS)
+        unless status.success?
+          return nil if err.match?(NO_PR)
+
+          raise CommandFailed, "gh pr view #{branch} failed — #{err.empty? ? out : err}"
+        end
+
+        view = JSON.parse(out, symbolize_names: true)
+        view[:state] == "OPEN" ? view : nil
+      end
+
+      # Opens a PR from `branch`.
+      #
+      # @param branch [String] the head branch
+      # @param title [String] the PR's title
+      # @param body [String] the PR's description
+      # @param draft [Boolean] open it as a draft
+      # @return [String] what `gh pr create` printed, the PR's URL
+      # @raise [CommandFailed] when `gh` refuses
+      def create_pull_request(branch:, title:, body:, draft: false)
+        args = ["pr", "create", "--head", branch, "--title", title, "--body", body]
+        args << "--draft" if draft
+        out, err, status = gh(*args)
+        raise CommandFailed, "gh pr create failed — #{err.empty? ? out : err}" unless status.success?
+
+        out
+      end
+
+      # Queues a squash merge for when the PR's checks pass.
+      #
+      # @param number [Integer] the PR's number
+      # @return [void]
+      # @raise [CommandFailed] when `gh` refuses
+      def merge_when_green(number)
+        _out, err, status = gh("pr", "merge", number.to_s, "--auto", "--squash")
+        raise CommandFailed, "gh pr merge --auto failed — #{err}" unless status.success?
+      end
+
+      # A tracked PR's state and head commit, read live: a push mints a new commit to clear.
+      #
+      # @param number [Integer] the PR's number
+      # @return [Hash{Symbol => Object}] `state`, `headRefOid` and `url`
+      # @raise [CommandFailed] when `gh` cannot read it
+      def pull_request(number)
+        parse(gh("pr", "view", number.to_s, "--json", "state,headRefOid,url"), "gh pr view failed")
+      end
+
+      # A tracked PR's checks, as `gh` reports them.
+      #
+      # @param number [Integer] the PR's number
+      # @return [Array<Hash{Symbol => Object}>] each check's `name`, `state`, `bucket`, `workflow`
+      # @raise [CommandFailed] when `gh` cannot read them
+      def checks(number)
+        parse(gh("pr", "checks", number.to_s, "--json", "name,state,bucket,workflow"), "gh pr checks failed")
+      end
+
+      private
+
+      def assert_sha!(value, owner)
+        return if value.to_s.match?(SHA_PATTERN)
+
+        raise Refusal, "#{owner}'s commit #{value.to_s.inspect} does not look like a sha"
+      end
+
+      def assert_carries!(tip, commit, owner, label)
+        _out, _err, status = git("merge-base", "--is-ancestor", "--", commit, tip)
+        return if status.success?
+
+        raise Refusal, "#{owner}'s own fix commit #{commit[0, 7]} is not an ancestor of #{label} " \
+                       "(#{tip[0, 7]}) — the PR must carry the commit the ledger says fixes it"
+      end
+
+      def parse(result, failure)
+        out, err, status = result
+        raise CommandFailed, "#{failure} — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        JSON.parse(out, symbolize_names: true)
+      end
+
+      def git(*) = run_tool("git", *)
+
+      def gh(*) = run_tool("gh", *)
+
+      def run_tool(tool, *)
+        out, err, status = Open3.capture3(tool, *, chdir: @repo_dir)
+        [out.strip, err.strip, status]
+      rescue Errno::ENOENT
+        raise Refusal, "#{tool} is not installed or not on PATH (or #{@repo_dir} is missing) — " \
+                       "the practice cannot open or check a pull request without it"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/github_checks.adapter

@@ -0,0 +1,9 @@
+# Binds the `CI` port to `GithubChecks` for any boot that loads the QualityControl chapter.
+# The implementation is required by name, not relative to this file, because the `.adapter` glob
+# never loads the sibling `.rb` and a copy of this directory (a fuzz boot) must share the one
+# implementation already loaded.
+require "hecks/quality_control/adapters/github_checks"
+
+Hecks.adapter "GithubChecks" do
+  port "CI"
+end

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `CI` port adapter: answers `Clearance.CI.Run` from GitHub's check runs for a commit.
+    # Raises when no checks exist, any are still running, or any failed.
+    class GithubChecks
+      # All keywords are unused; the adapter takes no per-boot configuration.
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Check-run conclusions that count as green; `skipped` covers path-filtered workflows.
+      PASSING = %w[success neutral skipped].freeze
+
+      # A commit sha as GitHub accepts it in an API path.
+      SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+      # Check runs asked for per page; GitHub's maximum.
+      PER_PAGE = 100
+
+      # Asks GitHub by commit sha, matching `Clearance`'s identity, so it works after the
+      # branch is gone. `{owner}/{repo}` is a `gh api` template resolved from the git remote.
+      #
+      # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
+      # @return [Hash] `{ summary: { value: ... } }` when every check is green
+      # @raise [RuntimeError] when the sha is malformed, `gh` is missing or fails, no checks
+      #   exist, any are incomplete, or any failed
+      def run(commit:, **)
+        sha = sha_of(commit)
+        raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
+
+        runs = check_runs(sha)
+
+        raise "gh reports no checks at all against #{sha}" if runs.empty?
+
+        # Refuse rather than answer on an incomplete run; asking again once it settles is safe.
+        incomplete = runs.reject { |run| run["status"] == "completed" }
+        raise "checks against #{sha} are still running — asked before they settled" if incomplete.any?
+
+        failing = runs.reject { |run| PASSING.include?(run["conclusion"]) }
+        return { summary: { value: "#{runs.length} checks, all green (#{sha[0, 7]})" } } if failing.empty?
+
+        raise "#{failing.length} of #{runs.length} checks failed against #{sha[0, 7]}: " \
+              "#{failing.map { |run| run['name'] }.join(', ')}"
+      end
+
+      private
+
+      # Accepts a materialized value hash with symbol or string keys, or a bare string.
+      def sha_of(commit)
+        return commit if commit.is_a?(String)
+
+        (commit.key?(:value) ? commit[:value] : commit["value"]).to_s
+      end
+
+      # Every page of check runs: a red run past the first page must still be seen.
+      def check_runs(sha)
+        runs = []
+        page = 1
+        loop do
+          batch = check_run_page(sha, page)["check_runs"] || []
+          runs.concat(batch)
+          break if batch.length < PER_PAGE
+
+          page += 1
+        end
+        runs
+      end
+
+      def check_run_page(sha, page)
+        path = "repos/{owner}/{repo}/commits/#{sha}/check-runs?per_page=#{PER_PAGE}&page=#{page}"
+        out, err, status = Open3.capture3("gh", "api", path)
+        raise "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        JSON.parse(out)
+      rescue Errno::ENOENT
+        raise "gh is not installed or not on PATH — cannot read check runs for #{sha}"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/github_ci_webhook.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "hecks/adapters/driving/github_webhook"
+require_relative "clearance_recorder"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Records GitHub's `check_suite` webhook as a `QualityControl::Clearance`.
+      # GitHub sends one `check_suite` per GitHub App for a commit, so one suite is not the
+      # commit's verdict. A passing suite clears the commit only when it belongs to `CI_APP_SLUG`
+      # (Actions, which runs the gate); a passing suite from any other app is acknowledged and
+      # ignored. A failing suite from any app holds the commit red, and the first verdict stands.
+      class GithubCiWebhook < GithubWebhook
+        SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+        # The GitHub App whose passing suite counts as the commit being green.
+        CI_APP_SLUG = "github-actions"
+
+        def handle_event(event, action, payload)
+          return ignored("not a check_suite event (got #{event.inspect})") unless event == "check_suite"
+          # `requested`/`rerequested` mean the suite has not finished, so there is no verdict yet.
+          return ignored("check_suite not yet completed (action=#{action.inspect})") unless action == "completed"
+
+          suite = payload["check_suite"] || {}
+          sha   = suite["head_sha"].to_s
+
+          unless sha.match?(SHA_PATTERN)
+            return [422, { error: "MalformedCommit", message: "check_suite.head_sha #{sha.inspect} does not look like a sha" }]
+          end
+
+          settle(sha, suite)
+        end
+
+        private
+
+        def ignored(reason) = [200, { ok: true, ignored: reason }]
+
+        def settle(sha, suite)
+          conclusion = suite["conclusion"].to_s
+          passed     = Hecks::QA::ClearanceRecorder::PASSING.include?(conclusion)
+          app        = suite.dig("app", "slug").to_s
+          if passed && app != CI_APP_SLUG
+            return ignored("passing check_suite from app #{app.inspect}, not #{CI_APP_SLUG.inspect}")
+          end
+
+          summary = "check_suite #{suite['id']} conclusion=#{conclusion} for #{sha[0, 7]} — via webhook"
+
+          cleared = Hecks::QA::ClearanceRecorder.record(commit: sha, passed: passed, summary: summary)
+
+          [200, { ok: true, commit: sha, status: cleared.status, summary: summary }]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/github_issues.adapter

@@ -0,0 +1,7 @@
+# Binds the `IssueTracker` port to `GithubIssues` for any boot that loads the chapter.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/github_issues"
+
+Hecks.adapter "GithubIssues" do
+  port "IssueTracker"
+end

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    # The `IssueTracker` port's adapter: files a `QualityControl::Ticket` as a GitHub issue.
+    # Raises when `gh` refuses, which the runtime records as the ticket's refusal.
+    class GithubIssues
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Files the ticket the runtime hands over (its whole held state) with `gh issue create`.
+      #
+      # @param held [Hash] the ticket's fields; `repository`, `title` and `body` are materialized
+      #   value objects (`{value: ...}`) or bare strings, and `pull_request` names a proposed fix
+      # @return [Hash{Symbol => Hash}] `number:` and `url:` of the issue, in the shape the
+      #   ticket's `Filed` command takes
+      # @raise [RuntimeError] when `gh` exits non-zero or prints no issue URL
+      def file(**held)
+        repository = plain(held[:repository])
+        proposed   = plain(held[:pull_request]).to_s
+        body       = plain(held[:body]).to_s
+        body      += "\n\nA fix is proposed in #{proposed}" unless proposed.empty?
+
+        out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
+                                          "--title", plain(held[:title]).to_s, "--body", body)
+        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        url    = out.strip.lines.last.to_s.strip
+        number = url[%r{/issues/(\d+)\z}, 1]
+        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+
+        { number: { value: number.to_i }, url: { value: url } }
+      end
+
+      private
+
+      # A materialized value object (`{value: x}`, symbol or string keys) or the value itself.
+      def plain(field)
+        return field unless field.is_a?(Hash)
+
+        field.key?(:value) ? field[:value] : field["value"]
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/qa_tool.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "hecks/runtime/errors"
+require_relative "../cli/child"
+
+module Hecks
+  module Adapters
+    # The base of the adapters that answer the QA scripts' queries (`SweepTools`,
+    # `ClearanceTools`, `AngleTools`, `TargetTools`): each starts one command of
+    # `Hecks::QualityControlCli` as its own OS process and answers what it printed.
+    #
+    # A child, not this process: the commands boot the ledger, fork, spawn and open Postgres
+    # connections of their own, and a crash or an `exit` in one must end only that run. The answer
+    # is the command's output, unchanged, so the launcher shows the bytes the script prints.
+    class QaTool
+      # A command ended in an error. It is a refusal, since the launcher and the ledger's policies
+      # treat it as one, but not a `given`'s: no description of the command's guards quotes it, so
+      # the fuzzer's guard checks must not read it as one.
+      class ToolRefused < Runtime::GivenNotMet; end
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the checkout the commands run in; this repository when nil
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || File.expand_path("../../../..", __dir__)
+      end
+
+      private
+
+      # Runs one command and answers its output.
+      #
+      # @param command [String] a key of `QualityControlCli::Child::COMMANDS`
+      # @param args [Array<String>] the command's own arguments
+      # @param answers [Array<Integer>] the exit statuses that are an answer: a finding, or a
+      #   judgment, is one, an operational error is not
+      # @return [Hash] `text:` what the command printed, stdout and stderr in
+      #   order
+      # @raise [ToolRefused] with what the command printed, when it ended with another
+      #   status
+      def run_command(command, *, answers: [0])
+        output, status = Open3.capture2e(*QualityControlCli::Child.argv(@root, command, *), chdir: @root)
+        return { text: output } if answers.include?(status.exitstatus)
+
+        raise ToolRefused, "#{output.strip}\n(#{command} ended with status #{status.exitstatus.inspect})"
+      end
+
+      # @param value [Hash, String, nil] a value object's materialized `{ value: "..." }`, or plain
+      #   text
+      # @return [String, nil] the text, nil when absent
+      def plain(value) = value.is_a?(Hash) ? value[:value] : value
+
+      # @param value [Hash, String, nil] words in the command's own flag syntax
+      # @return [Array<String>] the words, split as a shell would
+      def words(value) = Shellwords.split(plain(value).to_s)
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/sweep_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `SweepTools` port to `SweepTools`, which answers `Sweep`'s queries: a tick, a sweep, the Heki migration, the ledger's role and a racer.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/sweep_tools"
+
+Hecks.adapter "SweepTools" do
+  port "SweepTools"
+end