hecks 2.8.0 → 3.0.0

data/lib/hecks/projector.rb

@@ -1,60 +1,13 @@
 module Hecks
-  # A named registry of "canonical IR in, external artifact out" tools —
-  # §30 of docs/HECKS_IMPLEMENTATION_PLAN.md. Before this existed, every
-  # such tool was its own thing with its own call shape: `Exporter`
-  # (registry-wide, consumed directly by bin/ir, bin/project_rust, and
-  # translation/audit's approval digest — untouched by this file, still
-  # exactly what those three read), and `RustProjection::Projector`
-  # (`rust/project.rb`, a whole separate Ruby program under a
-  # confusingly-identical module name) are the two that already exist.
-  # Neither is registered here — retrofitting either is real, separate
-  # work (Rust's generator is a whole second toolchain; a UL/OIDC
-  # projector doesn't exist yet at all) — but `:ir` is, as a genuine,
-  # working, golden-tested example of the shape every future projector
-  # (`:rust`, `:ul`, `:openid`, ...) is meant to follow.
+  # A named registry of "canonical IR in, external artifact out" tools, each
+  # taking one bluebook's IR and answering a derived artifact (`:ir`, `:docs`, ...).
   #
-  # The unit is one bluebook's IR, not a whole booted registry — matching
-  # every real projection target (Rust/UL/OIDC all project one domain at
-  # a time), and deliberately narrower than `Exporter.call`'s own
-  # multi-domain shape.
+  #   Projector.call(:ir, bluebook: chapter)
   #
-  # ## Three kinds of "project"
-  #
-  # Told apart by what they need as input. Only the first belongs in this
-  # registry.
-  #
-  #   a projection takes a chapter's declaration and answers something
-  #   that describes the domain: its IR, its storage shape, an OIDC scope
-  #   manifest, the parser's keyword table, the reference pages. Inert,
-  #   derived, and runnable against any chapter that carries what it
-  #   declares it needs. These are what `register` holds.
-  #
-  #   an export takes a declaration and its bindings and answers
-  #   something that is the domain, running elsewhere — rust/project.rb's
-  #   generated crate, the WASM artifact, the CloudFormation template
-  #   `lib/hecks/projections/deploy` renders. It needs the
-  #   `.world`/`.hecksagon` a projection never looks at, because a
-  #   running system has to know how it is wired. A target that needs
-  #   this declares `needs_world: true` (`Target#projects_as`) and reads
-  #   `options.fetch(:world)`; `Projector.call`'s own `world:` keyword is
-  #   what carries it, merged into `options` before the target ever runs.
-  #
-  #   a state projection takes records — a domain after dispatch — and is
-  #   a read-model question wearing the same word.
-  #   `bin/expression_projection` is the one of these: its operators are
-  #   not declared anywhere, they are what exists after
-  #   `Grammar.expression` replays expression_operators.json's ledger of
-  #   dispatches. Converting it into this registry would be a category
-  #   error, however much its name suggests otherwise.
-  #
-  # ## One word, three other meanings
-  #
-  # Worth naming too, because grepping "projection" turns all of these up
-  # and none is the above:
-  #
-  #   Ports::Projection    read-model catch-up, events folded into state
-  #   bin/project          forces that catch-up by hand
-  #   RustProjection       rust/project.rb's own separate toolchain
+  # A projection is inert and derived from a chapter's declaration. An export
+  # (rust crate, WASM, CloudFormation) also needs `.world` bindings and declares
+  # `needs_world: true`. State projections (`hecks project_expression_tables`) and
+  # `Ports::Projection` read-model catch-up are different things and not registered.
   module Projector
     class UnknownProjector < StandardError; end
     # A chapter-scoped projector was handed something that is not a chapter.
@@ -62,14 +15,8 @@ module Hecks
 
     module_function
 
-    # `projector` needs only to answer `call(bluebook:, options:)` — a
-    # module, a class with a class method, or any object responding to
-    # `call` all work. Re-registering a name replaces it outright,
-    # deliberately unguarded: a spec re-registering a stub under the same
-    # name between examples is the ordinary case, not a footgun to fence
-    # against.
     # Adds `projector` to the registry under `name`, replacing anything
-    # already registered there.
+    # already registered there (deliberately unguarded, so specs can stub).
     #
     # @param name [String, Symbol] the key `projector` is looked up by (converted to a symbol)
     # @param projector [Module, Class, #call] anything answering `call(bluebook:, options:)`
@@ -81,24 +28,14 @@ module Hecks
     # Runs the projector registered under `name` against `bluebook`,
     # after refusing a construct it does not admit.
     #
-    # `bluebook:` is kept as the keyword because it is the shipped
-    # spelling and every existing caller uses it — but what it accepts is
-    # any construct that emits IR, and `admits!` is what decides whether
-    # this target can actually take the one handed over.
-    #
     # @param name [String, Symbol] the registered projector's key
-    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
-    #   IR-emitting construct to project
+    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to project
     # @param options [Hash] projector-specific options, passed through unchanged
-    # @param world [Bluebook::World, nil] the domain's `.world`/`.hecksagon` bindings,
-    #   required by an export (`needs_world: true`); nil for an ordinary projection.
-    #   Merged into `options[:world]` before the target runs — the target never
-    #   receives it as a separate argument.
-    # @return [Object] whatever the projector's own `call` returns: typically a
-    #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
+    # @param world [Bluebook::World, nil] bindings an export needs (`needs_world: true`);
+    #   merged into `options[:world]`
+    # @return [Object] whatever the projector's own `call` returns
     # @raise [UnknownProjector] if no projector is registered under `name`
-    # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
-    #   projector requires, or if the projector needs `world:` and none is given
+    # @raise [WrongConstruct] if `bluebook` lacks what the projector requires
     def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
@@ -107,31 +44,17 @@ module Hecks
       projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
     end
 
-    # Refuses `construct` if it lacks a capability or declared aggregate
-    # `projector` requires. A projection names the capabilities it needs;
-    # this is what enforces that, before the projector runs.
-    #
-    # One check covers both shapes. An ordinary construct includes its
-    # capabilities and a class-shaped one — Command, Entity, ValueObject
-    # — extends them, and `is_a?` consults the singleton chain, so it
-    # answers for an extended module as readily as an included one. This
-    # started as two checks on the assumption it would not; a spec
-    # asserting the assumption failed, which is the only reason the
-    # redundant half was noticed.
+    # Refuses `construct` if it lacks a capability or declared aggregate `projector` requires.
+    # One `is_a?` check covers included and extended capabilities alike.
     #
     # @param name [String, Symbol] the projector's registered key, used in the message
-    #   when refusing
-    # @param projector [Module, Class, #call] the target being checked; consulted for
-    #   `projection_requires`, `projection_declares`, and `projection_needs_world?` when
-    #   it answers them
-    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
-    #   IR-emitting construct offered to the projector
-    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`, checked
-    #   against the target's own `needs_world:` declaration
+    # @param projector [Module, Class, #call] the target; consulted for `projection_requires`,
+    #   `projection_declares` and `projection_needs_world?` when it answers them
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct offered
+    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`
     # @return [void]
-    # @raise [WrongConstruct] if `construct` lacks a required capability, the chapter it
-    #   is declares no aggregate the projector needs, or the projector needs `world:`
-    #   and `world` is nil
+    # @raise [WrongConstruct] if a required capability or aggregate is missing, or the
+    #   projector needs `world:` and `world` is nil
     def admits!(name, projector, construct, world = nil)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
@@ -190,11 +113,8 @@ module Hecks
       @registry ||= {}
     end
 
-    # A target may be addressed by the constant that implements it
-    # (`Projections::OIDC`) or by the bare key it registered under
-    # (`:oidc`). Both resolve here, so the constant form is added
-    # surface rather than a replacement — every `Projector.call(:ir, ...)`
-    # written before this existed keeps working untouched.
+    # Resolves a target given as a constant (`Projections::OIDC`) or a bare
+    # key (`:oidc`) to the key it is registered under.
     #
     # @param target [String, Symbol, #projection_key] a registered key, or a target
     #   that declared its own key with `Target#projects_as`
@@ -205,15 +125,10 @@ module Hecks
       target
     end
 
-    # Writing is the caller's choice, not the projector's. A projector
-    # returns an artifact and never touches disk, which is what lets
-    # spec/projector_spec.rb compare `:ir`'s output against a golden
-    # fixture without a tmpdir. `out:` is the only thing that writes.
+    # Writes `artifact` to `out`; a projector itself never touches disk.
     #
-    # `as:` comes from the projection's own `emits:` declaration rather
-    # than from inspecting the artifact. A Hash of path => contents and a
-    # Hash that simply happens to hold strings are the same object to
-    # Ruby; only the projection knows which it meant.
+    # `as:` comes from the projection's `emits:` declaration, since a file tree
+    # and a Hash of strings are the same object to Ruby.
     #
     # @param artifact [Hash, String] the projector's output; a file tree when `as: :files`
     # @param out [String] the path to write to; a directory when `as: :files`
@@ -226,8 +141,7 @@ module Hecks
       out
     end
 
-    # Answers the paths written, in the order given — so a caller can
-    # report what happened without re-deriving it from the tree.
+    # Writes each `files` entry under `directory`, answering the paths written.
     #
     # @param files [Hash{String => String}] relative path => contents
     # @param directory [String] the directory to write the tree under
@@ -249,8 +163,7 @@ require "json"
 require_relative "projector/exporter"
 require_relative "projector/ir_projector"
 require_relative "projector/target"
-# Neither of these requires this file back — they need `Naming` and nothing
-# else — so unlike a target they are safe to pull in from here.
+# These need only `Naming`, not this file, so they are safe to load from here.
 require_relative "projector/docs_projector"
 require_relative "projector/narrate_projector"
 require_relative "projector/cli_projector"
@@ -260,9 +173,5 @@ Hecks::Projector.register(:docs, Hecks::Projector::DocsProjector)
 Hecks::Projector.register(:narrate, Hecks::Projector::NarrateProjector)
 Hecks::Projector.register(:cli, Hecks::Projector::CliProjector)
 
-# The targets are required from lib/hecks.rb, immediately after this
-# file — deliberately not from here. A target requires this file (it
-# needs `Target` and the registry), so requiring them back from here
-# would close a genuine `circular require considered harmful` loop. Ruby
-# tolerates it; the warning is still right, and load order is the kind of
-# thing that only breaks once someone requires a target on its own.
+# Targets are required from lib/hecks.rb, not here: each requires this file, so
+# requiring them back would close a circular require.

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