hecks 3.0.3 → 3.0.4

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -73,7 +73,7 @@ Hecks.bluebook "Bluebook" do
 
     # Expression::CanonicalForm::STRATEGIES
     value_object "NormalisationStrategy" do
-      attribute :name, String, one_of: ["collapse_whitespace", "replace"]
+      attribute :name, String, one_of: ["collapse_whitespace", "replace", "scale_call"]
     end
 
     # Ops Runtime::CommandInterpreter applies. `sign` is the arithmetic delta
@@ -602,6 +602,34 @@ Hecks.bluebook "Bluebook" do
       member name: "textarea", pattern: '\b(text|body|note|notes|description|message|comment)\b', resolves_to: "kind"
     end
 
+    # The path gates the workflows run before an expensive job: one detector job
+    # per row, answering `touched` from the diff of the change against its base.
+    # hecks project_ci_gates writes each row into the marked region of its
+    # `workflow` (.github/workflows/<workflow>), and the job it writes runs
+    # `hecks decide_ci_gate gate=<name>`, which makes the decision from the row.
+    #
+    # `mode` is how `pattern` (an extended regex over changed paths) decides:
+    # `touches` runs the job when any changed path matches, `skips_unless` runs it
+    # when any changed path does NOT match (the pattern is the safe-to-skip list).
+    # `push` is what a push event does: `skip` leaves the gate out of push runs,
+    # `before_sha` diffs against the push's `before` commit.
+    value_object "CiGate" do
+      attribute :name,     String
+      attribute :workflow, String
+      attribute :mode,     String
+      attribute :pattern,  String
+      attribute :push,     String
+      attribute :label,    String
+
+      member name: "runtime_changed", workflow: "ci.yml", mode: "touches",
+             pattern: '^lib/hecks/runtime/', push: "skip",
+             label: "does this change touch lib/hecks/runtime/**?"
+      member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
+             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\.rb$|rust/project_rust_pipeline\.rb$|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
+             push: "before_sha",
+             label: "does this change touch anything rspec_postgres_io_parallel covers?"
+    end
+
     # Rust keywords (strict + reserved) a generated identifier must not
     # collide with. RustProjection::Projector::RUST_KEYWORDS reads this;
     # hecks project_reserved_names projects it into

data/lib/hecks/language/oidc.json

@@ -111,6 +111,11 @@
       "verb": "Bluebook::Command.Ensure",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:command.need",
+      "verb": "Bluebook::Command.Need",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.reference",
       "verb": "Bluebook::Command.Reference",

data/lib/hecks/ports/clock.rb

@@ -3,7 +3,9 @@ require_relative "../runtime/registry"
 module Hecks
   module Ports
     # What time it is, as one registry-wide adapter answers it.
-    # Predicates cannot read the clock (replays must be deterministic), so the door fills `now`.
+    # Predicates cannot read the clock (replays must be deterministic), so a command that declares
+    # `needs :now` has the runtime read it once, before any given runs, into the command's own
+    # `now` argument (ADR 0081). The recorded argument is what a replay sees.
     module Clock
       NAME = "clock".freeze
 

data/lib/hecks/projections/deploy/lambda.rb

@@ -85,7 +85,9 @@ module Hecks
                 memory:   { value: deploy_settings.fetch(:memory, 512) },
                 timeout:  { value: deploy_settings.fetch(:timeout, 10) },
                 database: { value: deploy_settings.fetch(:database, "Postgres") },
-                web: { value: deploy_settings.fetch(:web, "None") }
+                web: { value: deploy_settings.fetch(:web, "None") },
+                **%i[dispatch handler_module secret_env].select { |key| deploy_settings.key?(key) }
+                                                        .to_h { |key| [key, { value: deploy_settings[key].to_s }] }
               }
             ).instance
           rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
@@ -105,9 +107,6 @@ module Hecks
           # The module name `lambda_handler.rb` actually defines; named here
           # since `dispatch "None"` domains may each pick their own.
           webhook_handler_module = deploy_settings.fetch(:handler_module, "WebLambdaHandler")
-          if dispatch_none && !deploy_settings.key?(:handler_module)
-            raise ArgumentError, "#{world_file}'s deployed_to(\"AwsLambda\") declares dispatch \"None\" but no handler_module — add handler_module \"YourModuleName\" naming the module #{domain}/lambda_handler.rb defines."
-          end
 
           # Scans every loaded chapter, not just this domain's own — a
           # `uses_framework`-attached chapter can itself declare a cross-domain

data/lib/hecks/quality_control/quality_control.bluebook

@@ -238,6 +238,7 @@ Hecks.bluebook "QualityControl" do
       reference_to Target
       attribute :held_by,    Engineer
       attribute :now,        Instant
+      needs :now
 
       given("a live claim is not taken from the agent holding it") do
         status != "held" || claimed_at.value + window.value <= now.value
@@ -265,6 +266,7 @@ Hecks.bluebook "QualityControl" do
       # carry it. Required, so an omitted streak can neither blank the counter nor guess at it.
       reference_to Target
       attribute :now,          Instant
+      needs :now
       attribute :next_streak,  CleanStreak
       # Required: an in-process dispatch does not fill defaults for absent arguments, so an omitted
       # list refuses rather than blanks. `capabilities.value=""` is an honest value.
@@ -1115,6 +1117,7 @@ Hecks.bluebook "QualityControl" do
       reference_to Bug
       attribute :held_by, Engineer
       attribute :now,     Instant
+      needs :now
 
       given("a live claim is not taken from the agent holding it") do
         held_by.value == "nobody" || claimed_at.value + window.value <= now.value
@@ -1388,6 +1391,7 @@ Hecks.bluebook "QualityControl" do
       attribute :proposer,  Proposer
       # `now:` is filled from the clock port, as in `Target.Claim`; an explicit value wins.
       attribute :now,       Instant
+      needs :now
 
       sets :proposed_at, to: :now
 
@@ -1784,6 +1788,7 @@ Hecks.bluebook "QualityControl" do
       attribute :commit, CommitRef
       attribute :title,  PatchTitle
       attribute :now,    Instant
+      needs :now
 
       given("the branch is one this practice recognises as its own") { branch.value.start_with?("qa/") }
       given("the bug is fixed") { bug.status == "fixed" }
@@ -1921,6 +1926,7 @@ Hecks.bluebook "QualityControl" do
       attribute :branch, ImprovementBranch
       attribute :title,  ImprovementTitle
       attribute :now,    Instant
+      needs :now
 
       given("the branch is one this practice recognises as its own") { branch.value.start_with?("qa/") }
       given("the angle is under investigation") { angle.unset? || angle.status == "investigating" }

data/lib/hecks/runtime/command_interpreter.rb

@@ -83,10 +83,12 @@ module Hecks
 
       private
 
-      # No-op: `Routing` has already handed `call` a decoded argument hash,
-      # so there is nothing left to decode here yet. Kept as a step so the
-      # generated step enum has a slot to move the real decoder into later.
-      def step_decode_arguments(_ctx); end
+      # `Routing` has already handed `call` a decoded argument hash, so the one thing left to do
+      # here is answer the outside facts the command `needs`, before any refusal or given reads
+      # its arguments. Not traced: the step has always been invisible to a trace observer.
+      def step_decode_arguments(ctx)
+        ctx.args = enrich_arguments(ctx.command, ctx.args)
+      end
 
       def step_refuse_unknown_arguments(ctx)
         step(:refuse_unknown_arguments) { refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args) }

data/lib/hecks/runtime/entity_interpreter.rb

@@ -133,8 +133,11 @@ module Hecks
 
       private
 
-      # No-op — entities have no `decode_arguments` step of their own.
-      def step_decode_arguments(_ctx); end
+      # Answers the outside facts the entity command `needs`, as the aggregate interpreter does;
+      # the arguments are otherwise already decoded.
+      def step_decode_arguments(ctx)
+        ctx.args = enrich_arguments(ctx.command, ctx.args)
+      end
 
       # `extra_identity_heads:` covers every entity in `ctx.chain`, not just
       # the root — each hop is addressed by its own identity fields, which

data/lib/hecks/runtime/interpreting.rb

@@ -1,5 +1,6 @@
 require_relative "value"
 require_relative "aggregate_lock"
+require_relative "../ports/clock"
 
 module Hecks
   module Runtime
@@ -13,8 +14,36 @@ module Hecks
         interpreter.singleton_class.attr_accessor :trace
       end
 
+      # What answers each outside fact a command may `needs` (ADR 0081). A fact is answered once,
+      # before any given runs, and the answer rides in the command's own arguments, so the event
+      # records it and a replay re-dispatches the recorded value rather than asking again.
+      NEED_ANSWERS = { now: ->(registry) { Ports::Clock.now(registry) } }.freeze
+
       private
 
+      # Fills each outside fact the command `needs` and the caller left out. A value the caller
+      # supplied is kept, so a test or a back-fill can name its own time.
+      #
+      # @param command [Class] the command being dispatched
+      # @param args [Hash{Symbol => Object}] the arguments the caller passed
+      # @return [Hash{Symbol => Object}] `args`, with each missing needed fact answered
+      # @raise [Runtime::WiringError] when the port that answers a fact is not bound exactly once
+      def enrich_arguments(command, args)
+        missing = command.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
+        return args if missing.empty?
+
+        args.merge(missing.to_h { |fact| [fact, need_value(command, fact)] })
+      end
+
+      # The answer to one fact, in the shape the command's argument of that name takes: a bare
+      # Integer for an Integer attribute, else the one-field value object the language declares
+      # for an instant.
+      def need_value(command, fact)
+        answer    = NEED_ANSWERS.fetch(fact).call(@registry)
+        attribute = command.attributes.find { |held| held.name.to_s == fact.to_s }
+        attribute&.type.to_s == "Integer" ? answer : { value: answer }
+      end
+
       # Logged after the step's work, so trace order is completion order.
       def step(name)
         result = yield

data/lib/hecks/runtime/invocation.rb

@@ -207,8 +207,12 @@ module Hecks
                                            declared: declared)
         end
 
+        # A fact the command `needs` is not absent: the interpreter answers it before any refusal
+        # reads the arguments.
         def refuse_absent_facts!(declaring, offered, declared)
-          absent = declaring.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
+          needed = declaring.respond_to?(:needs) ? declaring.needs.map(&:to_sym) : []
+          absent = declaring.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } -
+                   offered.keys - needed
           return if absent.empty?
 
           raise AbsentArgument,

data/lib/hecks/runtime/loader.rb

@@ -28,18 +28,21 @@ module Hecks
       # @raise [Errno::ENOENT] if `path` names no domain directory
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
       def self.boot(path, shared: nil, install_doors: true, install_facade: nil, environment: FROM_ENV)
-        loading   = Ports::Loading.bootstrap
-        directory = loading.bluebook_directory(path)
-        root      = loading.shared_root(shared, directory)
-        registry  = Registry.new(root: File.dirname(directory))
-
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(root)
-          loading.load_domain(directory, environment: selected_environment(environment))
-        end
+        described = describe(path, shared: shared, environment: environment)
+        boot_described(described, install_doors: install_doors, install_facade: install_facade)
+      end
 
-        run_boot_gates!(registry, directory)
+      # Finishes a boot from declarations `describe` already loaded: runs every boot gate and binds
+      # the dispatcher, without reading the domain's files again.
+      #
+      # @param described [Described] what `describe` answered for the domain to boot
+      # @param install_doors [Boolean] install the `Widget::Item.Add(...)` global facade sugar
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
+      # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
+      def self.boot_described(described, install_doors: true, install_facade: nil)
+        registry = described.registry
+        run_boot_gates!(registry, described.directory)
         dispatcher = dispatcher_for(registry)
         redrive_outbox!(dispatcher)
         seed_privacy_markings!(dispatcher, registry)
@@ -47,7 +50,7 @@ module Hecks
       end
 
       # What `describe` answers: the loaded declarations and nothing bound to run them.
-      Described = Struct.new(:registry)
+      Described = Struct.new(:registry, :directory)
 
       # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
       # persistence adapter is resolved or bound, nothing connects to a database.
@@ -71,7 +74,7 @@ module Hecks
           loading.load_project(root)
           loading.load_domain(directory, environment: selected_environment(environment))
         end
-        Described.new(registry)
+        Described.new(registry, directory)
       end
 
       # The overlay a boot loads: the caller's own choice (nil meaning none), else the

data/lib/hecks/runtime.rb

@@ -62,6 +62,17 @@ module Hecks
         Loader.describe(path, shared: shared, environment: environment)
       end
 
+      # Finishes a boot from declarations `describe` already loaded. See Loader.boot_described.
+      #
+      # @param described [Runtime::Loader::Described] what `describe` answered
+      # @param install_doors [Boolean] whether to install the Ruby facade constants
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      #   to the booted domain
+      def boot_described(described, install_doors: true, install_facade: nil)
+        Loader.boot_described(described, install_doors: install_doors, install_facade: install_facade)
+      end
+
       # Loads only the given files of a domain; otherwise like `boot`. See Loader.boot_files.
       #
       # @param paths [String, Array<String>] one or more file paths within the domain

data/lib/hecks/three_zero/forms.yml

@@ -23,7 +23,7 @@ evolve: hecks word_status; hecks propose <word> context=X [body=none] [inner=] [
   [named=] [fills=] [pairs_shape=]; hecks admit_argument|deprecate_argument|retire_argument
   <word> context=X [at=N] [named=]
 expression_projection: hecks project_expression_tables [--stdout]
-follow: hecks follow <domain> [aggregate=Name] [since=N] [interval=0.5] [wait=N] [--from-now]
+follow: hecks follow <domain> [aggregate=Name] [since=N] [interval=0.5] [wait=N] [--from-now] [--stream]
 fuzz: hecks fuzz [domain] [seeds=20] [steps=30] [workers=] [adapter=memory]
 generate: hecks generate_sequence <domain> [seed=1] [steps=30] [adversarial=0.0]
 hecks_mcp_door: hecks mcp [--stdio]

data/lib/hecks/tools/ci_gate_decision.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/vocabulary"
+require_relative "../tools"
+require_relative "ci_gates"
+
+module Hecks
+  module Tools
+    # Answers whether a change touches what a gated CI job covers: the decision a `CiGate` row of
+    # the Vocabulary chapter names, made by `hecks decide_ci_gate gate=<name>` in the detector job
+    # `hecks project_ci_gates` writes into each workflow.
+    #
+    # The change is read from the run's own event (`GITHUB_EVENT_PATH`) and head (`GITHUB_SHA`),
+    # and the answer goes to stdout and, when the runner names one, to `GITHUB_OUTPUT` as
+    # `touched=true` or `touched=false`. Every case that cannot confirm a safe diff answers
+    # `true`, so a failure here runs the gated job instead of skipping it.
+    module CiGateDecision
+      NO_COMMIT = "0" * 40
+
+      module_function
+
+      # @param argv [Array<String>] `gate=<name>`, a `CiGate` row's name
+      # @param root [String] the checkout whose history is diffed
+      # @param env [Hash{String => String}] the runner's environment
+      # @return [Integer] 0 once an answer is given
+      # @raise [SystemExit] when no row has that name
+      def main(argv, root: Tools::ROOT, env: ENV)
+        name = argv.filter_map { |arg| arg[/\Agate=(.+)\z/, 1] }.first
+        abort "decide_ci_gate: name a gate, gate=<name>" unless name
+        gate = CiGates.gates.find { |row| row["name"] == name }
+        abort "decide_ci_gate: no CiGate row named #{name}" unless gate
+
+        touched = touched?(gate, root: root, env: env)
+        puts "touched=#{touched}"
+        File.open(env["GITHUB_OUTPUT"], "a") { |file| file.puts "touched=#{touched}" } if env["GITHUB_OUTPUT"]
+        0
+      end
+
+      # @param gate [Hash{String => String}] a `CiGate` row
+      # @param root [String] the checkout
+      # @param env [Hash{String => String}] the runner's environment
+      # @return [Boolean] whether the gated job should run
+      def touched?(gate, root:, env:)
+        base = base_of(gate, root: root, env: env)
+        if base.nil? || base.empty? || base == NO_COMMIT
+          explain(gate, "no usable base to diff against")
+          return true
+        end
+
+        changed = changed_files(base, env.fetch("GITHUB_SHA", "HEAD"), root: root)
+        if changed.nil?
+          explain(gate, "git diff itself failed")
+          return true
+        end
+        return false if changed.empty?
+
+        matches = changed.map { |path| path.match?(Regexp.new(gate.fetch("pattern"))) }
+        gate.fetch("mode") == "touches" ? matches.any? : matches.any?(false)
+      end
+
+      # The commit the change is measured against: a pull request's base, or a merge group's
+      # merge-base with its target branch, never the group's `base_sha`, which is the previous
+      # queue entry and would let an entry queued behind a red one diff as its own files only.
+      #
+      # @return [String, nil] the commit, or nil when there is none
+      def base_of(gate, root:, env:)
+        event = event_of(env)
+        base = event.dig("pull_request", "base", "sha").to_s
+        if env["GITHUB_EVENT_NAME"] == "merge_group"
+          target = event.dig("merge_group", "base_ref").to_s.delete_prefix("refs/heads/")
+          base = git(root, "merge-base", "origin/#{target}", env.fetch("GITHUB_SHA", "HEAD"))&.strip.to_s
+        end
+        base = event["before"].to_s if base.empty? && env["GITHUB_EVENT_NAME"] == "push" && gate["push"] == "before_sha"
+        base
+      end
+
+      # @return [Hash] the run's event payload, empty when it cannot be read
+      def event_of(env)
+        path = env["GITHUB_EVENT_PATH"].to_s
+        path.empty? || !File.file?(path) ? {} : JSON.parse(File.read(path))
+      rescue JSON::ParserError
+        {}
+      end
+
+      # @return [Array<String>, nil] the changed paths, or nil when git could not say
+      def changed_files(base, head, root:)
+        out = git(root, "diff", "--name-only", base, head)
+        return nil if out.nil?
+
+        out.lines.map(&:chomp).reject(&:empty?)
+      end
+
+      # @return [String, nil] a git command's stdout, or nil when it failed
+      def git(root, *)
+        out, _err, status = Open3.capture3("git", "-C", root, *)
+        status.success? ? out : nil
+      end
+
+      # Says why a gate could not be answered; the caller runs the gated job.
+      #
+      # @return [nil]
+      def explain(gate, reason)
+        warn "decide_ci_gate: #{reason} (#{gate['label']}): running the gated job rather than guessing"
+      end
+    end
+  end
+end

data/lib/hecks/tools/ci_gates.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Projects the `CiGate` rows of the Vocabulary chapter into the workflows: each row becomes a
+    # detector job between a pair of marker comments in its `workflow`. The job runs
+    # `hecks decide_ci_gate gate=<name>` (`CiGateDecision`), so the decision is made by the binary
+    # from the same row, never by shell the workflow carries.
+    #
+    # Everything outside the markers is hand-written and left alone. With `--check` nothing is
+    # written: the tool answers 1 and names each workflow whose region differs from the rows.
+    module CiGates
+      # Where the workflows live, relative to the checkout.
+      WORKFLOWS = ".github/workflows"
+
+      module_function
+
+      # @param argv [Array<String>] `--check` to compare without writing
+      # @param root [String] the checkout
+      # @return [Integer] 0, or 1 when `--check` finds a region out of date
+      # @raise [SystemExit] when a workflow has no marked region for a gate
+      def main(argv, root: Tools::ROOT)
+        stale = projection(root).reject { |path, text| File.read(path) == text }.keys
+        return report(stale, root) if argv.include?("--check")
+
+        stale.each { |path| File.write(path, projection(root).fetch(path)) }
+        stale.each { |path| puts "wrote #{path.delete_prefix("#{root}/")}" }
+        puts "ci_gates: #{gates.size} gates, every region current" if stale.empty?
+        0
+      end
+
+      # @param root [String] the checkout
+      # @return [Hash{String => String}] each workflow's absolute path to the text it should hold
+      def projection(root)
+        gates.group_by { |gate| gate.fetch("workflow") }.to_h do |workflow, rows|
+          path = File.join(root, WORKFLOWS, workflow)
+          [path, rows.reduce(File.read(path)) { |text, gate| replace_region(text, gate, workflow) }]
+        end
+      end
+
+      # The values a row's `mode` and `push` may take: the language holds one closed set to a value
+      # object, so the rest are held here.
+      MODES = %w[touches skips_unless].freeze
+      PUSHES = %w[skip before_sha].freeze
+
+      # @return [Array<Hash{String => String}>] the `CiGate` rows
+      # @raise [SystemExit] when a row's `mode` or `push` is not one the action understands
+      def gates
+        Hecks::Vocabulary.rows("CiGate").each do |gate|
+          abort "ci_gates: #{gate['name']} has mode #{gate['mode'].inspect}" unless MODES.include?(gate["mode"])
+          abort "ci_gates: #{gate['name']} has push #{gate['push'].inspect}" unless PUSHES.include?(gate["push"])
+        end
+      end
+
+      # @param stale [Array<String>] absolute paths whose text differs from the rows
+      # @param root [String] the checkout
+      # @return [Integer] 0 when current, else 1 with the stale workflows on stderr
+      def report(stale, root)
+        if stale.empty?
+          puts "ci_gates: #{gates.size} gates, every region current"
+          return 0
+        end
+
+        warn "ci_gates: out of date: #{stale.map { |path| path.delete_prefix("#{root}/") }.join(', ')} " \
+             "(run hecks project_ci_gates)"
+        1
+      end
+
+      # @param text [String] a workflow
+      # @param gate [Hash{String => String}] a `CiGate` row
+      # @param workflow [String] the workflow's file name, for the refusal
+      # @return [String] the workflow with the gate's marked region replaced by its job
+      def replace_region(text, gate, workflow)
+        name = gate.fetch("name")
+        region = /^  # BEGIN GENERATED ci_gate #{Regexp.escape(name)}\b.*?^  # END GENERATED ci_gate #{Regexp.escape(name)}$/m
+        abort "ci_gates: #{workflow} has no BEGIN/END GENERATED ci_gate #{name} region" unless text.match?(region)
+
+        text.sub(region) { job(gate) }
+      end
+
+      # @param gate [Hash{String => String}] a `CiGate` row
+      # @return [String] the marked region: the detector job that answers `touched`
+      def job(gate)
+        name = gate.fetch("name")
+        [
+          "  # BEGIN GENERATED ci_gate #{name} (CiGate vocabulary; hecks project_ci_gates). Do not hand-edit.",
+          "  #{name}:",
+          "    runs-on: ubuntu-latest",
+          "    timeout-minutes: 10",
+          *job_condition(gate),
+          "    outputs:",
+          "      touched: ${{ steps.diff.outputs.touched }}",
+          "    steps:",
+          "      - uses: actions/checkout@v4",
+          "        with:",
+          "          # Full history: the diff needs both endpoints present as real objects.",
+          "          fetch-depth: 0",
+          "      - uses: ./.github/actions/setup-ruby",
+          "      - uses: ./.github/actions/hecks-environment",
+          "      - id: diff",
+          "        name: #{quoted(gate.fetch('label'))}",
+          "        run: bundle exec exe/hecks decide_ci_gate gate=#{name} --wait",
+          "  # END GENERATED ci_gate #{name}"
+        ].join("\n")
+      end
+
+      # @param gate [Hash{String => String}] a `CiGate` row
+      # @return [Array<String>] the job-level `if:` lines for a gate that skips push runs
+      def job_condition(gate)
+        return [] unless gate.fetch("push") == "skip"
+
+        ["    # A push is a cache-warming run; the jobs that need this one skip through their `needs:`.",
+         "    if: github.event_name != 'push'"]
+      end
+
+      # @param text [String]
+      # @return [String] the text as a single-quoted YAML scalar
+      def quoted(text) = "'#{text.gsub("'", "''")}'"
+    end
+  end
+end

data/lib/hecks/tools/gate.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "open3"
+require "yaml"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Runs a stage's checks, which `lib/hecks/gate/stages.yml` holds as data, all at once and
+    # reports every one, so a red check does not hide the others.
+    #
+    #   hecks gate pre_push                # every check of the stage
+    #   hecks gate pre_push only=rubocop   # the named checks
+    #   hecks gate --list                  # the stages and their checks
+    #
+    # A green stage prints which checks passed; a red one prints each failing check's whole output
+    # and what its failure means, and answers status 1.
+    module Gate
+      STAGES_FILE = File.expand_path("../gate/stages.yml", __dir__)
+      USAGE = "usage: hecks gate <stage> [only=a,b] | hecks gate --list"
+
+      module_function
+
+      # @param argv [Array<String>] a stage name and optionally `only=a,b`, or `--list`
+      # @param root [String] the checkout the checks run in
+      # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
+      def main(argv, root: Tools::ROOT, **)
+        stages = YAML.load_file(STAGES_FILE)
+        return list(stages) if argv == ["--list"]
+
+        name = argv.find { |arg| !arg.include?("=") && !arg.start_with?("--") }
+        only = argv.filter_map { |arg| arg.delete_prefix("only=").split(",") if arg.start_with?("only=") }.flatten
+        stage = stages[name]
+        return usage(stages, name) unless stage
+
+        checks = select(stage.fetch("checks"), only)
+        return unknown(stage, only) if checks.nil?
+
+        report(name, checks, run_all(stage, checks, root))
+      end
+
+      # @param checks [Array<Hash>] a stage's checks
+      # @param only [Array<String>] the check ids asked for; every check when empty
+      # @return [Array<Hash>, nil] the checks to run, nil when an id names no check
+      def select(checks, only)
+        return checks if only.empty?
+        return nil unless (only - checks.map { |check| check["id"] }).empty?
+
+        checks.select { |check| only.include?(check["id"]) }
+      end
+
+      # Starts every check at once and waits for all of them.
+      #
+      # @param stage [Hash] the stage: its `env` and `checks`
+      # @param checks [Array<Hash>] the checks to run
+      # @param root [String] the directory they run in
+      # @return [Hash{String => Array}] each check's id, and its output and whether it passed
+      def run_all(stage, checks, root)
+        env = stage.fetch("env", {}).reject { |key, _| ENV.key?(key) }
+        threads = checks.map do |check|
+          Thread.new { [check["id"], run_one(check, env, root)] }
+        end
+        threads.to_h(&:value)
+      end
+
+      # @return [Array(String, Boolean)] what the check printed, and whether it exited 0
+      def run_one(check, env, root)
+        argv = check.fetch("run").map { |word| word.to_s.sub("{workers}", workers.to_s) }
+        output, status = Open3.capture2e(env, *argv, chdir: root)
+        [output, status.success?]
+      rescue SystemCallError => e
+        ["could not start #{argv.first}: #{e.message}", false]
+      end
+
+      # @return [Integer] half the machine's cores, at least one; the parallel suite at full width
+      #   starves the fuzzing run beside it
+      def workers
+        require "etc"
+        [Etc.nprocessors / 2, 1].max
+      end
+
+      def report(name, checks, results)
+        failed = checks.reject { |check| results.fetch(check["id"]).last }
+        failed.each do |check|
+          output, = results.fetch(check["id"])
+          puts "\n[gate #{name}] #{check['title']}\n\n#{output}"
+          puts "\n[gate #{name}] BLOCKED: #{check['blocked']}\n"
+        end
+        if failed.empty?
+          puts "[gate #{name}] green: #{checks.map { |check| check['id'] }.join(', ')}"
+          return 0
+        end
+
+        puts "[gate #{name}] red: #{failed.map { |check| check['id'] }.join(', ')}"
+        1
+      end
+
+      def list(stages)
+        stages.each do |name, stage|
+          puts "#{name}: #{stage.fetch('checks').map { |check| check['id'] }.join(', ')}"
+        end
+        0
+      end
+
+      def unknown(stage, only)
+        known = stage.fetch("checks").map { |check| check["id"] }
+        warn "no such check: #{(only - known).join(', ')} (checks: #{known.join(', ')})"
+        2
+      end
+
+      def usage(stages, name)
+        warn(name ? "no such stage: #{name} (stages: #{stages.keys.join(', ')})" : USAGE)
+        2
+      end
+    end
+  end
+end