hecks 5.0.0 → 7.0.0

data/lib/hecks/tools/gate_memo/ruby_files.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+require "yaml"
+require_relative "../gate_memo"
+
+module Hecks
+  module Tools
+    module GateMemo
+      # Decides how much of RuboCop a gate run needs. The green run's memo holds the hash of every
+      # Ruby
+      # file and of the configuration, and the run is skipped only when the files and their hashes
+      # are
+      # identical to it. Otherwise RuboCop lints the changed files and the files that require them,
+      # and
+      # a full run is made whenever that set cannot be worked out.
+      module RubyFiles
+        # Files whose change invalidates every verdict: the configuration and the local cops it
+        # loads.
+        CONFIG = %w[.rubocop.yml .rubocop_todo.yml Gemfile.lock lib/rubocop/cop/**/*.rb].freeze
+
+        # A `require` or `require_relative` line, and the path it names.
+        REQUIRE = /^\s*require(_relative)?\s+["']([^"']+)["']/
+
+        # Directories that hold Ruby the checkout does not own, or copies of it.
+        SKIPPED_DIRS = %w[.claude .git rust vendor node_modules tmp].freeze
+
+        module_function
+
+        # @param root [String] the checkout
+        # @return [Hash{String => String}] each Ruby file's path and sha256
+        def hashes(root)
+          listed(root).to_h { |rel| [rel, GateMemo.sha(root, rel)] }
+        end
+
+        # @return [Array<String>] the Ruby files of the checkout, sorted, the same set whether
+        #   or not the checkout is a git repository
+        def listed(root)
+          listing(root).reject { |rel| rel.split("/").intersect?(SKIPPED_DIRS) }.sort
+        end
+
+        # @return [Array<String>] the Ruby files git lists, or the ones on disk when git does not
+        def listing(root)
+          out, status = Open3.capture2("git", "-C", root, "ls-files", "-co", "--exclude-standard", "--", "*.rb",
+                                       err: File::NULL)
+          return out.split("\n") if status.success?
+
+          Dir.glob("**/*.rb", base: root)
+        end
+
+        # @param root [String] the checkout
+        # @param entry [Hash, nil] the memo's entry for rubocop: `inputs` (the config's digest) and
+        # `files`
+        # @param now [Hash{String => String}] the checkout's Ruby files and their hashes, as they
+        # are now
+        # @return [Array(Symbol, Array<String>, String)] the mode (`skip`, `incremental` or `full`),
+        # the
+        #   files to lint when incremental, and why
+        def plan(root, entry, now)
+          return [:full, [], "no green run is recorded"] unless entry.is_a?(Hash) && entry["files"].is_a?(Hash)
+          return [:full, [], "the configuration or a local cop changed"] unless entry["inputs"] == config(root)
+          return [:skip, [], "the Ruby files are unchanged"] if now == entry["files"]
+
+          incremental(root, entry["files"], now)
+        rescue SystemCallError, EncodingError, ArgumentError => e
+          [:full, [], "the Ruby files could not be read (#{e.message})"]
+        end
+
+        # @return [String] the digest of the configuration and the local cops
+        def config(root) = GateMemo.fingerprint(root, CONFIG)
+
+        # @return [Array(Symbol, Array<String>, String)] the files that changed, or were removed,
+        # and the
+        #   files that require them, less the ones `AllCops` Exclude names; skipped when only
+        #   excluded files changed, and a full run when a removal leaves nothing to lint
+        def incremental(root, was, now)
+          changed = now.keys.reject { |rel| was[rel] == now[rel] }
+          removed = was.keys - now.keys
+          set = lintable(root, closure(root, changed + removed, now.keys))
+          return nothing_to_lint(removed) if set.empty?
+
+          [:incremental, set, "#{set.size} of #{now.size} Ruby files: changed, removed or requiring them"]
+        end
+
+        # @return [Array(Symbol, Array<String>, String)] a full run when a removal left the set
+        #   empty, since an empty file list would make RuboCop lint the whole tree; otherwise a
+        #   skip, because only excluded files changed
+        def nothing_to_lint(removed)
+          return [:full, [], "removed files leave nothing to lint"] if removed.any?
+
+          [:skip, [], "only files the configuration excludes changed"]
+        end
+
+        # @return [Array<String>] the files that `AllCops` Exclude does not name, as RuboCop
+        #   applies it to a full run; an explicit file list would otherwise bypass it
+        def lintable(root, files)
+          globs = excludes(root)
+          files.reject { |rel| globs.any? { |glob| File.fnmatch?(glob, rel, File::FNM_PATHNAME) } }
+        end
+
+        # @return [Array<String>] the `AllCops` Exclude globs of the checkout's `.rubocop.yml`; none
+        #   when the file is absent
+        def excludes(root)
+          path = File.join(root, ".rubocop.yml")
+          return [] unless File.file?(path)
+
+          Array(YAML.safe_load_file(path, permitted_classes: [Symbol]).dig("AllCops", "Exclude"))
+        end
+
+        # @return [Array<String>] the seeds and every file that requires one, through
+        # require_relative
+        #   and require "hecks/..." lines, among the files now present
+        def closure(root, seeds, present)
+          reverse = requirers(root, present)
+          queue = seeds.dup
+          seen = queue.to_set
+          queue.shift.then { |rel| (reverse[rel] || []).each { |req| queue << req if seen.add?(req) } } until queue.empty?
+          seen.select { |rel| present.include?(rel) }.sort
+        end
+
+        # @return [Hash{String => Array<String>}] each file's requirers, keyed by the file it
+        # requires
+        def requirers(root, present)
+          present.each_with_object(Hash.new { |h, k| h[k] = [] }) do |rel, reverse|
+            requires(root, rel).each { |target| reverse[target] << rel }
+          end
+        end
+
+        # @return [Array<String>] the Ruby files that `rel` requires inside the checkout
+        def requires(root, rel)
+          source = File.read(File.join(root, rel))
+          source.scan(REQUIRE).filter_map do |relative, name|
+            relative ? resolve_relative(rel, name) : resolve_library(name)
+          end
+        end
+
+        # @return [String] the path a `require_relative` names, from the file that names it
+        def resolve_relative(rel, name)
+          target = name.end_with?(".rb") ? name : "#{name}.rb"
+          Pathname.new(File.join(File.dirname(rel), target)).cleanpath.to_s
+        end
+
+        # @return [String, nil] the library file a `require "hecks/x"` names under lib/; nil for a
+        # gem
+        def resolve_library(name)
+          "lib/#{name}.rb" if name.start_with?("hecks/")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/gate_memo/session.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../gate_memo"
+require_relative "ruby_files"
+
+module Hecks
+  module Tools
+    module GateMemo
+      # One stage's use of the memo: which checks a run skips, and what its green results record.
+      #
+      # A run calls `plan` before it starts and `record` once every check has answered. A check that
+      # passed is recorded with the inputs it ran on; a check that failed is forgotten, so it runs
+      # again.
+      class Session
+        # What a run does with the checks it was given.
+        #
+        # @!attribute [r] run
+        #   @return [Array<Hash>] the checks to run; rubocop with the files it lints when
+        # incremental
+        # @!attribute [r] skipped
+        #   @return [Array(Hash, String)] each skipped check and when its green run was recorded
+        # @!attribute [r] notes
+        #   @return [Array<String>] what the memo could not do, and how each planned check runs
+        Plan = Struct.new(:run, :skipped, :notes)
+
+        # @param root [String] the checkout
+        # @param env [Hash{String => String}] the environment the stage sets for its checks
+        # @param file [String] the memo's file
+        def initialize(root:, env:, file: GateMemo.path)
+          @root = root
+          @env = env
+          @file = file
+          @ran = []
+          @pending = {}
+          @notes = []
+        end
+
+        # @param checks [Array<Hash>] the checks a run was asked for
+        # @return [Plan] the checks to run and the ones skipped; every check runs when the memo is
+        # unusable
+        def plan(checks)
+          @memo, problem = GateMemo.read(@file)
+          @readable = problem.nil?
+          @memo ||= {}
+          @notes << "gate memo unusable (#{problem}): every check runs, and nothing is recorded" unless @readable
+          result = Plan.new([], [], @notes)
+          checks.each { |check| check["id"] == "rubocop" ? rubocop(check, result) : generic(check, result) }
+          result
+        end
+
+        # @param results [Hash{String => Array}] each check that ran: its output, and whether it
+        # passed
+        # @return [Array<String>] what could not be recorded; empty when the memo was written
+        def record(results)
+          return [] unless @readable
+
+          @ran.each { |id| update(id, results.fetch(id).last) }
+          error = GateMemo.write(@memo, @file)
+          error ? ["gate memo not written (#{error}): the next run runs these checks in full"] : []
+        end
+
+        private
+
+        # @return [void] a check with declared inputs is skipped when its inputs hash as its green
+        # run did
+        def generic(check, result)
+          tree = GateMemo.tree(@root, check["id"])
+          inputs = GateMemo.digest(@root, check, @env, tree)
+          entry = @memo[check["id"]]
+          return result.skipped << [check, entry["at"]] if GateMemo.reusable?(entry, inputs)
+
+          run(check, result, inputs ? GateMemo.green(inputs, tree) : nil)
+        end
+
+        # @return [void] RuboCop runs on the files its green run did not cover, or on all of them
+        def rubocop(check, result)
+          entry = @memo["rubocop"]
+          now = RubyFiles.hashes(@root)
+          mode, files, why = RubyFiles.plan(@root, entry, now)
+          return result.skipped << [check, entry["at"]] if mode == :skip
+
+          result.notes << "rubocop #{mode}: #{why}"
+          run(rubocop_check(check, mode, files), result, rubocop_entry(now))
+        end
+
+        # @return [Hash] the check, with the files it lints appended when the run is incremental
+        def rubocop_check(check, mode, files)
+          mode == :incremental ? check.merge("run" => check["run"] + files) : check
+        end
+
+        # @return [Hash] the green entry a passing RuboCop run records: its config and every Ruby
+        # file
+        def rubocop_entry(now) = GateMemo.green(RubyFiles.config(@root)).merge("files" => now)
+
+        # @return [void] the check joins the run; its green entry is kept when it passes
+        def run(check, result, entry)
+          result.run << check
+          @ran << check["id"]
+          @pending[check["id"]] = entry
+        end
+
+        # @return [void] keeps a passed check's entry, and forgets a check that did not pass
+        def update(id, passed)
+          entry = @pending[id]
+          if passed && entry
+            @memo[id] = entry
+          else
+            @memo.delete(id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/gate_memo/standalone.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../gate_memo"
+
+module Hecks
+  module Tools
+    module GateMemo
+      # The gate's memo, read by a check that is also run by hand. A green run of the check, in the
+      # gate or alone, is kept with the digest of the files it read (`tree`); the check is skipped
+      # when it is asked again on that same tree. Only a check that changes nothing asks: a run that
+      # confirms, rewrites or names a part of the corpus never skips.
+      module Standalone
+        module_function
+
+        # @param id [String] a check id
+        # @return [String] the memo key a run by hand keeps its own green result under, so it never
+        #   replaces the gate's entry for the check
+        def key(id) = "standalone:#{id}"
+
+        # @param root [String] the checkout
+        # @param id [String] a check id with declared inputs in `GateMemo::INPUTS`
+        # @param file [String] the memo's file
+        # @return [String, nil] when the gate or a run by hand last passed the check on exactly
+        #   these files; nil to run it
+        def passed_at(root, id, file: GateMemo.path, tree: GateMemo.tree(root, id))
+          memo, problem = GateMemo.read(file)
+          return nil if problem || tree.nil?
+
+          entries = [memo[id], memo[key(id)]].select { |e| e.is_a?(Hash) && e["result"] == "green" }
+          entries.find { |entry| entry["tree"] == tree }&.fetch("at")
+        end
+
+        # @param root [String] the checkout
+        # @param id [String] a check id with declared inputs
+        # @param file [String] the memo's file
+        # @return [void] keeps a green entry for the check on the files it read now; an unreadable
+        #   memo is left as it is
+        def record(root, id, file: GateMemo.path, tree: GateMemo.tree(root, id))
+          memo, problem = GateMemo.read(file)
+          return if problem || tree.nil?
+
+          memo[key(id)] = GateMemo.green(tree, tree)
+          GateMemo.write(memo, file)
+        end
+
+        # Runs the block unless the check already passed on these files, and keeps its pass. The
+        # files are read before the block runs, so an edit made while it runs is not credited to it.
+        #
+        # @param root [String] the checkout
+        # @param id [String] a check id with declared inputs
+        # @param file [String] the memo's file
+        # @return [String, Object] the skip line, or what the block returned when it did not raise
+        def guard(root, id, file: GateMemo.path)
+          tree = GateMemo.tree(root, id)
+          at = passed_at(root, id, file: file, tree: tree)
+          return skipped_line(at) if at
+
+          yield.tap { record(root, id, file: file, tree: tree) }
+        end
+
+        # @param at [String] when the green run was recorded
+        # @return [String] what a skipped check says
+        def skipped_line(at) = "skipped as unchanged since #{at}"
+      end
+    end
+  end
+end

data/lib/hecks/tools/gate_memo.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+require "time"
+require_relative "gate_memo/local_files"
+
+module Hecks
+  module Tools
+    # The gate's memo of green runs, kept outside the checkout. A check whose inputs hash the same
+    # as
+    # the inputs of its last green run is reported as skipped, never as passed. The inputs of a
+    # check
+    # are the files it reads (the globs in `INPUTS`, hashed by content), together with the command
+    # and
+    # the environment it runs under. A red result is never kept, so a red check runs again next
+    # time.
+    #
+    # The rule itself is declared in the Check bluebook beside `GateRun`, in
+    # lib/hecks/hecks/check/check.bluebook.
+    module GateMemo
+      # Build output is never an input: a Rust target directory is large, and its tool rebuilds
+      # it (`target` and `node_modules`).
+      BUILD_DIRS = %w[target node_modules .git].freeze
+
+      # Where the memo is kept, unless `HECKS_GATE_MEMO` names another file.
+      DEFAULT_PATH = File.join(Dir.home, ".claude", "hecks-dev", "gate_memo.json")
+
+      # The files each check reads, as globs under the checkout. A glob is wide where the check
+      # reads a whole tree: a change to any file a check could read reruns it, and a check is
+      # skipped only when none of them moved. A check with no entry here is never skipped.
+      SHAPE = %w[lib/**/*.rb lib/**/*.bluebook lib/**/*.hecksagon lib/**/*.world lib/**/*.json
+                 lib/**/*.adapter translations/**/*].freeze
+      STYLE = %w[lib/**/*.rb spec/**/*.rb docs/COMMENT_STYLE_GUIDE.md].freeze
+      SPEC = %w[spec/spec_helper.rb spec/support/**/*.rb].freeze
+      LIBRARY = %w[lib/**/*].freeze
+      SOURCE = %w[lib/**/* spec/**/* examples/**/* qa/**/* exe/**/* bin/**/* docs/**/* rust/**/* .github/**/*
+                  Gemfile Gemfile.lock *.gemspec .rubocop.yml .rubocop_todo.yml].freeze
+      RUST = %w[rust/**/*.rs rust/**/Cargo.toml rust/**/Cargo.lock rust/rust-toolchain.toml
+                rust-toolchain.toml].freeze
+      MODEL = %w[lib/**/*.rb lib/**/*.bluebook lib/**/*.hecksagon lib/**/*.world examples/**/*].freeze
+
+      # What the code, the rust tree and the bundle hold: everything the whole-tree checks read
+      # except prose, workflows and lint settings.
+      CODE = %w[lib/**/* spec/**/* examples/**/* exe/**/* bin/**/* rust/**/* Gemfile Gemfile.lock *.gemspec].freeze
+      # `spec/fuzzing` runs the specs and the corpus against the library and the rust tree
+      # (`rust/` is read for the target capabilities), and boots the stress domains, the QA bluebook
+      # and the settings under `qa/`. No spec in it reads `docs/` or `.github/`.
+      FUZZING = CODE + %w[qa/**/*]
+      # The reference-docs check reads the words of the language (`lib/`) against the pages of
+      # `docs/implemented/reference/` and nothing else.
+      DOC_COVERAGE = %w[lib/**/* docs/implemented/reference/**/* Gemfile Gemfile.lock *.gemspec].freeze
+      # Regenerating the corpus reads its bluebooks, hecksagons and worlds (`lib/`, `examples/`,
+      # `qa/`, `packages/`, the fixtures and corpus specs the corpus routes name), the generator
+      # (`lib/`, `rust/codegen`) and the committed output (`rust/`). It reads no prose.
+      CODEGEN = %w[lib/**/* examples/**/* qa/**/* packages/**/* spec/fixtures/**/* spec/corpus/**/* exe/**/*
+                   bin/**/* rust/**/* Gemfile Gemfile.lock *.gemspec].freeze
+
+      INPUTS = {
+        "shape_ledger"     => SHAPE,
+        "comment_style"    => STYLE,
+        "comment_blocks"   => STYLE + %w[examples/**/*.rb],
+        "secret_output"    => LIBRARY + SPEC + %w[spec/secret_output_spec.rb],
+        "adapter_words"    => LIBRARY + SPEC + %w[spec/adapter_words_spec.rb],
+        "rspec"            => SOURCE,
+        "fuzzing"          => FUZZING,
+        "query_agreement"  => SOURCE,
+        "engine_agreement" => SOURCE,
+        "model_check"      => MODEL,
+        "doc_coverage"     => DOC_COVERAGE,
+        "codegen_drift"    => CODEGEN,
+        "rust_fmt"         => RUST
+      }.freeze
+
+      # The sha of each file this process has hashed, by path, modification time, size and inode, so
+      # the checks of one run that read the same tree hash each file once.
+      SHAS = {} # rubocop:disable Style/MutableConstant
+
+      module_function
+
+      # @return [String] the memo's file: `HECKS_GATE_MEMO` when set, else `DEFAULT_PATH`
+      def path = ENV.fetch("HECKS_GATE_MEMO", DEFAULT_PATH)
+
+      # @param file [String] the memo's file
+      # @return [Array(Hash, String)] the memo and nil; nil and why it could not be read. A missing
+      #   file is an empty memo, not a problem.
+      def read(file = path)
+        return [{}, nil] unless File.exist?(file)
+
+        memo = JSON.parse(File.read(file))
+        memo.is_a?(Hash) ? [memo, nil] : [nil, "#{file} does not hold a JSON object"]
+      rescue SystemCallError, JSON::ParserError => e
+        [nil, "#{file}: #{e.message}"]
+      end
+
+      # @param memo [Hash] the memo to keep
+      # @param file [String] the memo's file
+      # @return [String, nil] nil when it was written, else why it could not be
+      def write(memo, file = path)
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, "#{JSON.pretty_generate(memo)}\n")
+        nil
+      rescue SystemCallError => e
+        "#{file}: #{e.message}"
+      end
+
+      # The files a checkout owns: the ones git tracks and the ones it would add. A file git
+      # ignores (a run's data directory, a build's output, a log) is never an input: a check's own
+      # run rewrites those, so hashing them made the next run's inputs differ from the last.
+      #
+      # @param root [String] the checkout
+      # @return [Array<String>, nil] its files relative to the checkout; nil when `root` is not a
+      #   git checkout
+      def owned(root)
+        out, status = Open3.capture2("git", "-C", root, "ls-files", "-co", "--exclude-standard", "-z",
+                                     err: File::NULL)
+        status.success? ? out.split("\0") : nil
+      rescue SystemCallError
+        nil
+      end
+
+      # @param root [String] the checkout
+      # @param globs [Array<String>] globs under the checkout
+      # @return [Array<String>] the regular files the globs name, relative to the checkout, sorted;
+      #   in a git checkout only the files it owns
+      def files(root, globs)
+        own = owned(root)
+        matched = globs.flat_map { |glob| Dir.glob(glob, base: root) }.uniq
+        matched &= own if own
+        matched.reject { |rel| rel.split("/").intersect?(BUILD_DIRS) }
+               .select { |rel| File.file?(File.join(root, rel)) }.sort
+      end
+
+      # @param root [String] the checkout
+      # @param rel [String] a file relative to the checkout
+      # @return [String] the sha256 of the file's content
+      def sha(root, rel)
+        path = File.join(root, rel)
+        stat = File.stat(path)
+        key = [path, stat.mtime.to_r, stat.size, stat.ino]
+        SHAS.fetch(key) { SHAS[key] = Digest::SHA256.file(path).hexdigest }
+      end
+
+      # @param root [String] the checkout
+      # @param globs [Array<String>] the files to fingerprint
+      # @param local [Boolean] whether the checkout's local worlds are read too
+      # @return [String] one digest of each file's path and content, in path order
+      def fingerprint(root, globs, local: false)
+        rows = files(root, globs).map { |rel| "#{rel} #{sha(root, rel)}" }
+        rows += LocalFiles.files(root).map { |rel| "#{rel} #{sha(root, rel)}" } if local
+        Digest::SHA256.hexdigest(rows.join("\n"))
+      end
+
+      # @param root [String] the checkout
+      # @param check [Hash] a check: its `id` and its `run` words
+      # @param env [Hash{String => String}] the environment the stage sets for the check
+      # @return [String, nil] the digest of the check's command, environment and inputs; nil when
+      # the
+      #   check has no declared inputs, or one of them cannot be read, so it is never skipped
+      def digest(root, check, env, tree = tree(root, check["id"]))
+        return nil unless tree
+
+        words = ["run #{check["run"].join(" ")}", "env #{env.sort.map { |pair| pair.join("=") }.join(" ")}"]
+        Digest::SHA256.hexdigest("#{words.join("\n")}\n#{tree}")
+      end
+
+      # @param root [String] the checkout
+      # @param id [String] a check's id
+      # @return [String, nil] the digest of the files the check reads, whatever command runs it;
+      #   nil when it has no declared inputs or one of them cannot be read
+      def tree(root, id)
+        globs = INPUTS[id]
+        globs && fingerprint(root, globs, local: LocalFiles::BOOTING.include?(id))
+      rescue SystemCallError
+        nil
+      end
+
+      # @param entry [Hash, nil] the memo's entry for a check
+      # @param inputs [String, nil] the check's digest now
+      # @return [Boolean] whether the entry is a green run on exactly these inputs
+      def reusable?(entry, inputs)
+        !inputs.nil? && entry.is_a?(Hash) && entry["result"] == "green" && entry["inputs"] == inputs
+      end
+
+      # @param inputs [String] the digest of the command, the environment and the files
+      # @param tree [String, nil] the digest of the files alone, which a standalone run of the same
+      #   check compares with
+      # @return [Hash] a green entry for a check that ran on these inputs
+      def green(inputs, tree = nil)
+        { "result" => "green", "at" => Time.now.utc.iso8601, "inputs" => inputs }.merge(tree ? { "tree" => tree } : {})
+      end
+    end
+  end
+end

data/lib/hecks/tools/gate_report.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    # Prints a gate run's verdict: the notes the memo left, the checks it skipped as unchanged, the
+    # output and meaning of each red check, and the summary line. A skipped check is printed as
+    # skipped, never as passed, and the verdict counts only the checks that ran.
+    module GateReport
+      module_function
+
+      # @param name [String] the stage name
+      # @param plan [GateMemo::Session::Plan] the checks that ran and the ones skipped as unchanged
+      # @param results [Hash{String => Array}] each check's output and whether it passed
+      # @param notes [Array<String>] what the memo could not record
+      # @return [Integer] 0 when every check that ran passed, 1 otherwise
+      def report(name, plan, results, notes = [])
+        (plan.notes + notes).each { |note| puts "[gate #{name}] #{note}" }
+        plan.skipped.each { |check, since| print_skipped(name, check, since) }
+        failed = print_failures(name, plan.run, results)
+        return summary(name, "red", failed, plan.skipped, 1) unless failed.empty?
+
+        summary(name, "green", plan.run, plan.skipped, 0)
+      end
+
+      # @return [Array<Hash>] the checks that did not pass, after printing each one's output and
+      # meaning
+      def print_failures(name, checks, results)
+        checks.reject { |check| results.fetch(check["id"]).last }.each do |check|
+          print_failure(name, check, results.fetch(check["id"]).first)
+        end
+      end
+
+      # @return [void] prints a check the memo skipped, as skipped and never as passed
+      def print_skipped(name, check, since)
+        puts "[gate #{name}] #{check["id"]}: unchanged, skipped (green as of #{since})"
+      end
+
+      # @return [Integer] the given status, after printing the stage's verdict, the checks that ran
+      # and
+      #   the checks skipped as unchanged
+      def summary(name, verdict, checks, skipped, status)
+        ran = checks.map { |check| check["id"] }
+        line = "[gate #{name}] #{verdict}: #{ran.empty? ? "nothing ran" : ran.join(", ")}"
+        line += "; skipped as unchanged: #{skipped.map { |check, _| check["id"] }.join(", ")}" if skipped.any?
+        puts line
+        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
+    end
+  end
+end

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

@@ -2,9 +2,10 @@
 
 require "json"
 require_relative "../../hecks"
+require_relative "persistence_notice"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks history` and `hecks history`: every journal entry a domain's
     # append-only adapters hold, as JSON, the full write history rather than the current head.
     module History
@@ -18,7 +19,9 @@ module Hecks
       # @raise [SystemExit] when `argv` is empty
       def call(argv, program: "hecks history")
         domain = argv.first or abort "usage: #{program} <domain>"
-        puts JSON.generate(document(Hecks.boot(domain).registry))
+        registry = Hecks.boot(domain).registry
+        PersistenceNotice.announce(registry, program: program)
+        puts JSON.generate(document(registry))
       end
 
       # @param registry [Runtime::Registry] a booted domain's registry

data/lib/hecks/tools/hoist_local_givens/rewriting.rb

@@ -105,11 +105,12 @@ module Hecks
         # `seg` with each of the candidate's occurrences swapped for a bare reference.
         def bare_references(seg, pattern, candidate)
           seg.gsub(pattern) do
-            indent, predicate_src = Regexp.last_match.captures
+            match = Regexp.last_match
+            indent, predicate_src = match.captures
             if matching_occurrence?(predicate_src, candidate)
               "#{indent}given(#{candidate.description.inspect})\n"
             else
-              Regexp.last_match(0)
+              match[0]
             end
           end
         end

data/lib/hecks/tools/hoist_local_givens.rb

@@ -104,10 +104,8 @@ module Hecks
       # @param registry [Object] the booted bluebooks
       # @return [Hash{String => Array}] each command's rules, by location
       def command_rule_map(registry)
-        Hecks::QueryIR.collect_rules(registry)
-                      .reject { |r| r.location.end_with?(" (declared)") }
-                      .group_by(&:location)
-                      .transform_values { |rules| rules.map { |r| [r.kind, r.description, r.canonical] }.sort }
+        local = Hecks::QueryIR.collect_rules(registry).reject { |r| r.location.end_with?(" (declared)") }
+        local.group_by(&:location).transform_values { |rules| rules.map { |r| [r.kind, r.description, r.canonical] }.sort }
       end
 
       # @param files [Array<String>] one example domain's bluebook files

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

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 require_relative "../ports/agent"
 
 module Hecks
-  module CLI
+  module Tools
     # The interviewer an interview session talks to: the agent port, resolved against a registry
     # that holds one adapter (ADR 0088). The session never sees the adapter, only validated
     # questions and proposals, so a spec can stand a scripted adapter in for the real one.

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

@@ -2,7 +2,7 @@ require_relative "../naming"
 require_relative "interview_shape"
 
 module Hecks
-  module CLI
+  module Tools
     # The bluebook text of one accepted thing: its aggregate, with its value objects, commands and
     # lifecycle. `InterviewDraft` extends it, and supplies the naming and citing helpers it calls.
     module InterviewAggregate