hecks 6.0.0 → 7.0.0

data/lib/hecks/{cli → tools}/doc_coverage.rb

@@ -4,7 +4,7 @@ require_relative "../../hecks"
 require_relative "../doc/reference"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks measure_doc_coverage`: refuses unless every live word in
     # `docs/implemented/reference/` has prose and a running example. It checks that an example
     # exists; `spec/reference_doctest_spec.rb` checks that it passes. `ruby skip` fences and
@@ -24,7 +24,7 @@ module Hecks
         return 0 if clean
 
         err.puts "docs/implemented/reference/ is behind the language. " \
-                 "Regenerate with hecks language_run.project_reference to see the words in place."
+                 "Regenerate with hecks language_run.project_reference! to see the words in place."
         1
       end
     end

data/lib/hecks/{cli → tools}/document.rb

@@ -1,7 +1,7 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks docs` and `hecks narrate`:
     # one domain's document, projected from its own bluebook, to stdout.
     #

data/lib/hecks/{cli → tools}/domain_stub.rb

@@ -1,7 +1,7 @@
 require_relative "../naming"
 
 module Hecks
-  module CLI
+  module Tools
     # The files `hecks init` writes: a stub domain that boots as it stands and that the author
     # then edits into a real one (ADR 0087).
     #

data/lib/hecks/{cli → tools}/domain_writer.rb

@@ -1,7 +1,7 @@
 require "fileutils"
 
 module Hecks
-  module CLI
+  module Tools
     # Writes the files `hecks init` and `hecks interview` produce, never replacing one (ADR 0087).
     #
     # Every target is checked before the first is written, so a refusal leaves nothing half-written.

data/lib/hecks/tools/downstream_model_check.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module Tools
+    # The model check a domain repository runs in its CI, generated from Hecks' own definition of it:
+    # the client profile, over the domain's bluebooks, from the hecks the Gemfile pins.
+    #
+    # A downstream repository commits the file this writes (`.github/workflows/model-check.yml`) and
+    # never edits it; a change to the check is made here, and every repository regenerates from it.
+    #
+    #   ruby lib/hecks/tools/downstream_model_check.rb <checkout> <domain-directory> [--check]
+    #
+    # With `--check` nothing is written: the tool answers 1 when the committed file differs.
+    module DownstreamModelCheck
+      # Where the workflow lives under the checkout.
+      FILE = ".github/workflows/model-check.yml"
+
+      # The hecks profile the check runs under (Hecks' client profile, which refuses what the
+      # client cannot answer for).
+      PROFILE = "client"
+
+      # The bluebook directory the check reads, relative to the domain directory.
+      DOMAINS = "bluebook"
+
+      # The Ruby the check runs on, matching the domain repositories' CI.
+      RUBY_VERSION = "3.3"
+
+      BANNER = "# Generated by hecks lib/hecks/tools/downstream_model_check.rb from Hecks' client-profile model " \
+               "check. Do not edit; change the generator in hecks."
+
+      module_function
+
+      # @param domain_directory [String] the directory the domain's Gemfile and bluebooks live in,
+      #   relative to the checkout (`.` when they are at the root)
+      # @return [String] the workflow's text, ending in a newline
+      def workflow(domain_directory:)
+        <<~YAML
+          #{BANNER}
+
+          name: Model check
+
+          on:
+            pull_request:
+            push:
+              branches: [main]
+            workflow_dispatch: {}
+
+          permissions:
+            contents: read
+
+          jobs:
+            model-check:
+              runs-on: ubuntu-24.04
+              timeout-minutes: 15
+              steps:
+                - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+                - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1
+                  with:
+                    ruby-version: "#{RUBY_VERSION}"
+                    bundler-cache: false
+
+                # The generator ships inside the pinned hecks gem, so the file is checked against the
+                # same generator that a bump brings in: a hand edit, or a stale file after a bump, fails here.
+                - name: Generated workflow is current
+                  working-directory: #{domain_directory}
+                  run: |
+                    bundle install --quiet --jobs 4
+                    ruby "$(bundle info hecks --path)/lib/hecks/tools/downstream_model_check.rb" "$GITHUB_WORKSPACE" #{domain_directory} --check
+
+                - name: Model check (hecks #{PROFILE} profile)
+                  working-directory: #{domain_directory}
+                  env:
+                    HECKS_ENVIRONMENT: memory
+                  run: |
+                    bundle install --quiet --jobs 4
+                    bundle exec hecks model_check_run.model_check! profile=#{PROFILE} domains=#{DOMAINS} --wait
+        YAML
+      end
+
+      # Writes the workflow under `root`, or with `check` compares it and reports whether it is current.
+      #
+      # @param root [String] the checkout
+      # @param domain_directory [String] see {workflow}
+      # @param check [Boolean] compare without writing
+      # @return [Integer] 0 when written or current, 1 when `check` finds the file out of date
+      def main(root:, domain_directory:, check: false)
+        path = File.join(root, FILE)
+        text = workflow(domain_directory: domain_directory)
+        current = File.file?(path) && File.read(path) == text
+        return check_report(current, path) if check
+        return puts("#{FILE}: already current") && 0 if current
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, text)
+        puts "wrote #{FILE}"
+        0
+      end
+
+      # @return [Integer] 0 when the file is current, else 1 with the reason on stderr
+      def check_report(current, path)
+        if current
+          puts "#{FILE}: current"
+          return 0
+        end
+
+        warn "#{FILE}: out of date at #{path} (regenerate with downstream_model_check.rb)"
+        1
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  root, domain_directory, flag = ARGV
+  abort "usage: downstream_model_check.rb <checkout> <domain-directory> [--check]" unless root && domain_directory
+
+  exit Hecks::Tools::DownstreamModelCheck.main(root: root, domain_directory: domain_directory,
+                                               check: flag == "--check")
+end

data/lib/hecks/tools/evolve_run.rb

@@ -103,7 +103,7 @@ module Hecks
 
       # @return [Boolean] true if the block ran and the gates held; false after restoring the
       #   snapshots when a gate refused
-      def edit_and_gate(word, context, evolve, root, &) # rubocop:disable Naming/PredicateMethod -- the edit's verdict
+      def edit_and_gate(word, context, evolve, root, &)
         paths = evolve.syntax_paths + [File.join(root, "spec/golden/ir/Bluebook.json")]
         snapshots = paths.to_h { |path| [path, File.read(path)] }
         evolve.restore_on_raise(paths, &)
@@ -124,7 +124,7 @@ module Hecks
       end
 
       # @return [true]
-      def status(evolve) # rubocop:disable Naming/PredicateMethod -- the command always succeeds
+      def status(evolve)
         rows = evolve.keyword_rows
         moving = rows.reject { |row| row[:status] == "admitted" }
         renamed = rows.reject { |row| row[:was].to_s.empty? }

data/lib/hecks/{cli → tools}/expected_era.rb

@@ -3,7 +3,7 @@ require "net/http"
 require "uri"
 
 module Hecks
-  module CLI
+  module Tools
     # Compares a running host's reported era (`GET /version`) against an
     # allow-list file of eras that should be running, for use after a roll. It is the HTTP side of
     # `hecks check_era`, which the `HostHttp` adapter runs; the runtime never calls it.

data/lib/hecks/{cli → tools}/expression_projection.rb

@@ -3,7 +3,7 @@
 require_relative "../projection_files"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks project_expression_tables`: projects the expression machinery's
     # operator and normalisation tables from the grammar bluebook into
     # `lib/hecks/bluebook/expression/projection.json`.

data/lib/hecks/{cli → tools}/follow.rb

@@ -5,7 +5,7 @@ require "optparse"
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks follow`: live-tails a domain's persisted event log as JSON lines.
     #
     # Events are one table per domain, so this polls the first repository that answers `:events`

data/lib/hecks/tools/fuzz_sweep/options.rb

@@ -9,21 +9,24 @@ module Hecks
       # The command line of a sweep: its options, and what the chosen adapter needs.
       module Options
         # The options that take a whole number, and the key each fills.
-        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers }.freeze
+        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers,
+                            "--list-shards" => :list_shards }.freeze
 
         # The most children a Postgres sweep runs at once unless `--workers` says otherwise.
         POSTGRES_WORKERS = 4
 
         # @param args [Array<String>] the command line, consumed
-        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist` and `domain`; nil
-        #   after a refusal
+        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist`, `domain`, `shard`
+        #   (the shard's number and the shard count) and `list_shards` (how many shards to list);
+        #   nil after a refusal
         def parse(args)
-          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false }
+          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false,
+                      shard: nil, list_shards: nil }
           until args.empty?
             apply_option(options, args.shift, args)
             return nil unless adapter_known?(options[:adapter])
           end
-          options
+          settle_shards(options)
         end
 
         # Records one command-line word in `options`, taking its value from `rest` when it has one.
@@ -31,10 +34,42 @@ module Hecks
           if (key = INTEGER_OPTIONS[arg]) then options[key] = Integer(rest.shift)
           elsif arg == "--persist-regressions" then options[:persist] = true
           elsif arg == "--adapter" then options[:adapter] = adapter_name(rest.shift)
+          elsif arg == "--shard" then options[:shard] = rest.shift.to_s
           else options[:domain] = arg
           end
         end
 
+        # Turns `--shard I/N` into the pair it names, and refuses the shard options that do not fit
+        # together or with what they split.
+        #
+        # @param options [Hash] the options as typed
+        # @return [Hash, nil] the options with `shard` parsed, or nil after a refusal
+        def settle_shards(options)
+          return options if options.values_at(:shard, :list_shards).none?
+          return nil unless shard_choice_clear?(options)
+
+          options[:shard] &&= Shards.parse_shard(options[:shard])
+          options.values_at(:shard, :list_shards).any? ? options : nil
+        end
+
+        # @return [Boolean] whether the shard options name one split of the corpus; warns why not
+        def shard_choice_clear?(options)
+          reason = shard_conflict(options)
+          warn reason if reason
+          reason.nil?
+        end
+
+        # @return [String, nil] why the shard options cannot be used together, or nil when they can
+        def shard_conflict(options)
+          if options[:shard] && options[:list_shards]
+            "--shard sweeps one shard and --list-shards lists them all; use one"
+          elsif options[:domain]
+            "shards split every domain of the checkout, so no domain can be named"
+          elsif options[:list_shards] && !options[:list_shards].positive?
+            "--list-shards takes a shard count of 1 or more"
+          end
+        end
+
         # @param word [String, nil] the word after `--adapter`
         # @return [Symbol] the adapter it names, lowercased
         def adapter_name(word) = word.to_s.downcase.to_sym

data/lib/hecks/tools/fuzz_sweep/pool.rb

@@ -16,16 +16,27 @@ module Hecks
         # @yieldparam domain [String] a domain directory
         # @yieldreturn [Boolean] whether it was clean
         # @return [Boolean] true if every domain's child exited 0, false if any exited non-zero
-        def fuzz_in_pool(domains, workers, &) # rubocop:disable Naming/PredicateMethod -- the sweep's verdict
+        def fuzz_in_pool(domains, workers, &)
           results = run_children(domains, workers, &)
           slowest = results.max_by(5) { |_, (_, _, seconds)| seconds }
                            .map { |index, (_, _, seconds)| "#{File.basename(domains[index])} #{seconds.round}s" }
           warn "slowest domains: #{slowest.join(", ")}"
+          warn "domain seconds: #{seconds_by_domain(domains, results)}"
           replay_outputs(results).all?
         end
 
         private
 
+        # Every domain's wall seconds, so a cost table can be read off one run's log.
+        #
+        # @return [String] `directory seconds` for each domain, in domain order, the directory
+        #   relative to the working directory when it lies under it
+        def seconds_by_domain(domains, results)
+          results.sort.map do |index, (_, _, seconds)|
+            "#{domains[index].delete_prefix("#{Dir.pwd}/")} #{seconds.round(1)}"
+          end.join(", ")
+        end
+
         # @return [Hash{Integer => Array}] by domain index: whether the child succeeded, its output
         #   file, and its seconds
         def run_children(domains, workers, &)

data/lib/hecks/tools/fuzz_sweep/shards.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module FuzzSweep
+      # Splits the domains of a sweep into `n` shards, so `n` jobs together sweep every domain once.
+      #
+      # The split is a pure function of the domain list, `n` and the committed cost table: no clock,
+      # no discovery order and no run history reach it, so every job computes the same partition.
+      # Domains are dealt, dearest first, to whichever shard holds the least cost so far, which
+      # keeps the shards near one another in cost; a domain the table does not name costs the
+      # table's median, and an absent table costs every domain the same.
+      module Shards
+        # What `--shard` takes: the shard's number, a slash, and how many shards there are.
+        SHARD_WORD = %r{\A([1-9]\d*)/([1-9]\d*)\z}
+
+        # Where the committed cost table is read from, relative to the checkout: one
+        # `directory:seconds` line for each domain, `#` lines being notes.
+        COST_TABLE = "spec/fuzzing/fuzz_runtime_baseline.log"
+
+        # What a domain costs when no table says: every domain alike.
+        FLAT_COST = 1.0
+
+        # A split that left a domain out or put one in two shards.
+        class NotAPartition < StandardError; end
+
+        module_function
+
+        # @param word [String, nil] the word after `--shard`
+        # @return [Array(Integer, Integer), nil] the shard's number and the shard count, or nil when
+        #   the word is not `I/N` with `I` between 1 and `N`; warns what is accepted
+        def parse_shard(word)
+          match = SHARD_WORD.match(word.to_s)
+          return [match[1].to_i, match[2].to_i] if match && match[1].to_i <= match[2].to_i
+
+          warn "unknown --shard #{word.inspect} — use I/N with I from 1 to N, such as 1/2, 2/2 or 3/4"
+          nil
+        end
+
+        # @param domains [Array<String>] the domain directories, each unique
+        # @param shards [Integer] how many shards to split into
+        # @param costs [Hash{String => Float}] each domain directory's cost, perhaps lacking some
+        # @return [Array<Array<String>>] the domains of each shard, each in the order `domains` has
+        def partition(domains, shards, costs = {})
+          price = prices(domains, costs)
+          order = domains.each_index.sort_by { |index| [-price[index], domains[index]] }
+          deal(order, price, shards).map { |indexes| indexes.sort.map { |index| domains[index] } }
+        end
+
+        # @param order [Array<Integer>] the domain positions, in the order to deal them
+        # @param price [Array<Float>] each position's cost
+        # @param shards [Integer] how many shards to deal into
+        # @return [Array<Array<Integer>>] the positions each shard took, each to the lightest shard
+        #   so far, the lowest numbered when they tie
+        def deal(order, price, shards)
+          loads = Array.new(shards, 0.0)
+          order.each_with_object(Array.new(shards) { [] }) do |index, taken|
+            lightest = loads.each_index.min_by { |shard| [loads[shard], shard] }
+            loads[lightest] += price[index]
+            taken[lightest] << index
+          end
+        end
+
+        # @param domains [Array<String>] the domain directories
+        # @param number [Integer] the shard wanted, from 1
+        # @param shards [Integer] how many shards there are
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @return [Array<String>] the domains that shard sweeps
+        def select(domains, number, shards, costs = {}) = partition(domains, shards, costs).fetch(number - 1)
+
+        # The assignment as data: one line for each domain, `I/N<TAB>cost<TAB>directory`, shard by
+        # shard. A split that left a domain out or put one in two shards is refused, since a job
+        # that reads this list would then trust a sweep that covers less than it says.
+        #
+        # @param domains [Array<String>] the domain directories
+        # @param shards [Integer] how many shards to split into
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @param root [String] the checkout the directories are shown relative to
+        # @return [Array<String>] the lines
+        # @raise [NotAPartition] when the shards are not a partition of `domains`
+        def listing(domains, shards, costs, root)
+          split = partition(domains, shards, costs)
+          raise NotAPartition, "the shards are not a partition of the domains" unless split.flatten.sort == domains.sort
+
+          price = domains.zip(prices(domains, costs)).to_h
+          split.each_with_index.flat_map do |members, index|
+            members.map { |domain| row("#{index + 1}/#{shards}", price[domain], domain.delete_prefix("#{root}/")) }
+          end
+        end
+
+        def row(shard, price, directory) = "#{shard}\t#{price.round(1)}\t#{directory}"
+
+        # Every discoverable domain, or the share of them `--shard I/N` asks for, which a pool
+        # starts dearest first so the longest domain is never the last one left running.
+        #
+        # @param options [Hash] the parsed options: `shard`, perhaps
+        # @param root [String] the checkout
+        # @return [Array<String>] the domain directories this sweep covers
+        def domains_for(options, root)
+          domains = Hecks::Corpus.fuzzable_domains(root)
+          return domains unless options[:shard]
+
+          number, shards = options[:shard]
+          puts "shard #{number}/#{shards}"
+          costs = costs_from(root)
+          dearest_first(select(domains, number, shards, costs), costs)
+        end
+
+        # @param domains [Array<String>] the domain directories
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @return [Array<String>] the same domains, dearest first, ties in path order
+        def dearest_first(domains, costs)
+          price = domains.zip(prices(domains, costs)).to_h
+          domains.sort_by { |domain| [-price[domain], domain] }
+        end
+
+        # Prints the listing of every domain of the checkout, and sweeps nothing.
+        #
+        # @param shards [Integer] how many shards to split into
+        # @param root [String] the checkout
+        # @return [Integer] 0 once printed
+        def print_listing(shards, root)
+          puts listing(Hecks::Corpus.fuzzable_domains(root), shards, costs_from(root), root)
+          0
+        end
+
+        # @param root [String] the checkout
+        # @return [Hash{String => Float}] seconds by absolute domain directory, from the committed
+        #   table; empty when the table is absent
+        def costs_from(root)
+          path = File.join(root, COST_TABLE)
+          return {} unless File.file?(path)
+
+          File.readlines(path, chomp: true).reject { |line| line.strip.empty? || line.start_with?("#") }
+              .to_h { |line| line.split(":", 2).then { |dir, seconds| [File.join(root, dir), Float(seconds)] } }
+        end
+
+        # @return [Array<Float>] each domain's cost, a missing one at the table's median
+        def prices(domains, costs)
+          fallback = median(costs.values) || FLAT_COST
+          domains.map { |domain| costs.fetch(domain, fallback) }
+        end
+
+        def median(values)
+          return nil if values.empty?
+
+          ranked = values.sort
+          (ranked[(ranked.size - 1) / 2] + ranked[ranked.size / 2]) / 2.0
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/fuzz_sweep.rb

@@ -8,6 +8,7 @@ require_relative "fuzz_sweep/options"
 require_relative "fuzz_sweep/findings"
 require_relative "fuzz_sweep/reporting"
 require_relative "fuzz_sweep/pool"
+require_relative "fuzz_sweep/shards"
 
 module Hecks
   module Tools
@@ -15,11 +16,13 @@ module Hecks
     # properties, then shrinks each distinct finding and saves it under `tmp/fuzz-failures/`.
     #
     #   hecks fuzz [domain] [--seeds N] [--steps N] [--workers N] [--adapter memory|sqlite|postgres]
-    #               [--persist-regressions]
+    #               [--persist-regressions] [--shard I/N | --list-shards N]
     #
     # The sweep is single-runtime on purpose; the cross-runtime differential is
     # `spec/rust_conformance_fuzz_spec.rb`. Without a domain it sweeps every domain
-    # `Hecks::Corpus.fuzzable_domains` finds, one forked child per core.
+    # `Hecks::Corpus.fuzzable_domains` finds, one forked child per core. `--shard I/N` sweeps only
+    # shard I of N (see `Shards`), so N jobs together sweep every domain once; `--list-shards N`
+    # prints which shard each domain falls in and sweeps nothing.
     module FuzzSweep
       # How many seeds are drawn for each seed that must execute.
       DRAW_LIMIT = 5
@@ -57,13 +60,16 @@ module Hecks
       #   argument is refused
       def main(argv, root: Tools::ROOT)
         require "hecks"
-        require "hecks/fuzzing"
         options = parse(argv.dup)
-        return 1 unless options && adapter_ready?(options)
+        return 1 unless options
+        return Shards.print_listing(options[:list_shards], root) if options[:list_shards]
+
+        require "hecks/fuzzing"
+        return 1 unless adapter_ready?(options)
 
         # Every discoverable domain, so one added anywhere is swept without a list. Paths the sweep
         # cannot boot are routed by Hecks::Corpus::ROUTES to the check that owns them.
-        domains = options[:domain] ? [options[:domain]] : Hecks::Corpus.fuzzable_domains(root)
+        domains = options[:domain] ? [options[:domain]] : Shards.domains_for(options, root)
         ok = sweep(domains, worker_count(options), options, root)
 
         puts(ok ? "CLEAN — no generated sequence broke a property or the interpreter." : "FUZZ FOUND SOMETHING.")

data/lib/hecks/tools/gate.rb

@@ -3,6 +3,9 @@
 require "open3"
 require "hecks/vocabulary"
 require_relative "../tools"
+require_relative "stage_progress"
+require_relative "gate_memo/session"
+require_relative "gate_report"
 
 module Hecks
   module Tools
@@ -14,10 +17,17 @@ module Hecks
     #   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.
+    # and what its failure means, and answers status 1. A check whose inputs are unchanged since its
+    # last green run is not run: it is printed as skipped, and the verdict counts it as skipped, not
+    # passed (see GateMemo).
     module Gate
       USAGE = "usage: hecks gate <stage> [only=a,b] | hecks gate --list"
 
+      # RuboCop keys its cache by file content, so one directory shared by every worktree lets each
+      # reuse the others' results. It is set here, in the gate's child environment, and not in
+      # .rubocop.yml, so CI and a bare `rubocop` keep the defaults (ADR 0091).
+      RUBOCOP_CACHE_ROOT = File.join(Dir.home, ".cache", "hecks", "rubocop")
+
       module_function
 
       # @return [Hash{String => Hash}] each stage by name: its `env` and its `checks`, in order,
@@ -45,8 +55,9 @@ module Hecks
 
       # @param argv [Array<String>] a stage name and optionally `only=a,b`, or `--list`
       # @param root [String] the checkout the checks run in
+      # @param progress [StageProgress] where each check's start and end lines go
       # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
-      def main(argv, root: Tools::ROOT, **)
+      def main(argv, root: Tools::ROOT, progress: StageProgress.new, **)
         stages = self.stages
         return list(stages) if argv == ["--list"]
 
@@ -57,7 +68,17 @@ module Hecks
         checks = select(stage.fetch("checks"), only)
         return unknown(stage, only) if checks.nil?
 
-        report(name, checks, run_all(stage, checks, root))
+        run_planned(name, stage, checks, root, progress)
+      end
+
+      # Runs the checks the memo does not skip, records the green ones, and reports the stage.
+      #
+      # @return [Integer] the verdict of `report`
+      def run_planned(name, stage, checks, root, progress)
+        session = GateMemo::Session.new(root: root, env: stage.fetch("env", {}))
+        plan = session.plan(checks)
+        results = run_all(stage, plan.run, root, progress)
+        GateReport.report(name, plan, results, session.record(results))
       end
 
       # @param argv [Array<String>] the command line words
@@ -83,18 +104,30 @@ module Hecks
       # @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
+      # @param progress [StageProgress] told when each check starts and ends
       # @return [Hash{String => Array}] each check's id, and its output and whether it passed
-      def run_all(stage, checks, root)
+      def run_all(stage, checks, root, progress)
         env = stage.fetch("env", {}).reject { |key, _| ENV.key?(key) }
         threads = checks.map do |check|
-          Thread.new { [check["id"], run_one(check, env, root)] }
+          progress.start(check["id"])
+          Thread.new { [check["id"], run_timed(check, env, root, progress)] }
         end
         threads.to_h(&:value)
       end
 
+      # @return [Array(String, Boolean)] what the check printed, and whether it exited 0; the end
+      #   line is written as the check finishes
+      def run_timed(check, env, root, progress)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        output, passed = run_one(check, env, root)
+        progress.finish(check["id"], passed, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+        [output, passed]
+      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) }
+        env = { "RUBOCOP_CACHE_ROOT" => RUBOCOP_CACHE_ROOT }.merge(ENV.slice("RUBOCOP_CACHE_ROOT")).merge(env)
         output, status = Open3.capture2e(env, *argv, chdir: root)
         [output, status.success?]
       rescue SystemCallError => e
@@ -108,30 +141,6 @@ module Hecks
         [Etc.nprocessors / 2, 1].max
       end
 
-      # @param name [String] the stage name
-      # @param checks [Array<Hash>] the checks that ran
-      # @param results [Hash{String => Array}] each check's output and whether it passed
-      # @return [Integer] 0 when every check passed, 1 otherwise
-      def report(name, checks, results)
-        failed = checks.reject { |check| results.fetch(check["id"]).last }
-        failed.each { |check| print_failure(name, check, results.fetch(check["id"]).first) }
-        return summary(name, "red", failed, 1) unless failed.empty?
-
-        summary(name, "green", checks, 0)
-      end
-
-      # @return [Integer] the given status, after printing the stage's verdict and its check ids
-      def summary(name, verdict, checks, status)
-        puts "[gate #{name}] #{verdict}: #{checks.map { |check| check["id"] }.join(", ")}"
-        status
-      end
-
-      # @return [void] prints a failing check's output and what its failure means
-      def print_failure(name, check, output)
-        puts "\n[gate #{name}] #{check["title"]}\n\n#{output}"
-        puts "\n[gate #{name}] BLOCKED: #{check["blocked"]}\n"
-      end
-
       def list(stages)
         stages.each do |name, stage|
           puts "#{name}: #{stage.fetch("checks").map { |check| check["id"] }.join(", ")}"