hecks 3.10.0 → 3.12.0

data/lib/hecks/tools/release_only.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/vocabulary"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Decides whether a commit is only a release bump on a base that is fully certified, so CI may
+    # inherit the base's certification instead of running the suite again.
+    #
+    # The files a bump edits, and which of their lines it may change, are the `ReleaseFile` rows of
+    # the Vocabulary chapter. A change is a release bump when it touches at least one file, every
+    # file it touches is a row, and every line it adds or removes in a file matches that row's
+    # `lines` pattern (an empty pattern admits any line). Whether the base is certified is read
+    # from the base commit's own check runs: every `RequiredCheck` row that is not marked
+    # `runs: always` must have its latest run on the base succeed or be skipped.
+    #
+    # Every case that cannot be confirmed answers "not a release bump", so the suite runs.
+    module ReleaseOnly
+      GREEN = %w[success skipped].freeze
+
+      module_function
+
+      # @param changes [Hash{String => Array<String>}] each changed path to the lines it adds or
+      #   removes
+      # @param files [Array<Hash{String => String}>] the `ReleaseFile` rows
+      # @return [Boolean] whether the change touches only release files, and only their release
+      #   lines
+      def release_only?(changes, files: Hecks::Vocabulary.rows("ReleaseFile"))
+        return false if changes.empty?
+
+        by_path = files.to_h { |row| [row.fetch("path"), row.fetch("lines", "")] }
+        changes.all? { |path, lines| by_path.key?(path) && lines_allowed?(lines, by_path.fetch(path)) }
+      end
+
+      # @param lines [Array<String>] the changed lines of one file
+      # @param pattern [String] the row's `lines` regex, empty for any line
+      # @return [Boolean] whether every changed line matches
+      def lines_allowed?(lines, pattern)
+        return true if pattern.to_s.empty?
+
+        regex = Regexp.new(pattern)
+        lines.all? { |line| line.match?(regex) }
+      end
+
+      # @param runs [Array<Hash{String => String}>] the base commit's check runs: `name`,
+      #   `conclusion` and `started_at`
+      # @param required [Array<Hash{String => String}>] the `RequiredCheck` rows
+      # @return [Boolean] whether every check that must be inherited has a green latest run
+      def certified?(runs, required: Hecks::Vocabulary.rows("RequiredCheck"))
+        latest = latest_runs(runs)
+        inherited = required.reject { |row| row["runs"] == "always" }.map { |row| row.fetch("name") }
+        inherited.all? { |name| GREEN.include?(latest[name].to_h["conclusion"]) }
+      end
+
+      # @return [Hash{String => Hash}] each check's most recently started run
+      def latest_runs(runs)
+        runs.group_by { |run| run["name"] }.transform_values { |group| group.max_by { |run| run["started_at"].to_s } }
+      end
+
+      # @param base [String] the commit the change is measured against
+      # @param head [String] the commit under test
+      # @param root [String] the checkout
+      # @return [Hash{String => Array<String>}, nil] each changed path to its changed lines, or nil
+      #   when git could not say
+      def changes(base, head, root:)
+        out, _err, status = Open3.capture3("git", "-C", root, "diff", "-U0", "--no-color", base, head)
+        status.success? ? parse(out) : nil
+      end
+
+      # @param diff [String] `git diff -U0` output
+      # @return [Hash{String => Array<String>}] each changed path to the lines it adds or removes
+      def parse(diff)
+        found = Hash.new { |hash, key| hash[key] = [] }
+        path = nil
+        diff.each_line do |line|
+          path = file_of(line.chomp) || path
+          found[path] << line[1..].chomp if path && content_line?(line)
+        end
+        found.to_h
+      end
+
+      # @return [String, nil] the path a `+++` or `---` header names, nil for any other line
+      def file_of(line)
+        return line.delete_prefix("+++ b/") if line.start_with?("+++ b/")
+
+        line.delete_prefix("--- a/") if line.start_with?("--- a/")
+      end
+
+      # @return [Boolean] whether the line is an added or removed line, not a header
+      def content_line?(line)
+        line.match?(/\A[+-]/) && !line.start_with?("+++ ", "--- ")
+      end
+
+      # @param repository [String] `owner/name`
+      # @param sha [String] the commit whose check runs are read
+      # @param env [Hash{String => String}] carries `GH_TOKEN` for the API call
+      # @return [Array<Hash{String => String}>, nil] the check runs, or nil when the API failed
+      def check_runs(repository, sha, env: ENV)
+        path = "repos/#{repository}/commits/#{sha}/check-runs?per_page=100"
+        jq = ".check_runs[] | {name, conclusion, started_at}"
+        out, _err, status = Open3.capture3(env.to_h.slice("GH_TOKEN"), "gh", "api", path, "--paginate", "--jq", jq)
+        status.success? ? out.lines.map { |line| JSON.parse(line) } : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/tools/site_routes/editor_files.rb

@@ -18,18 +18,25 @@ module Hecks
           setting = Projections::Site::CmsEditor::Setting.read(site.chapter, table: site.table)
           abort "project_site: --editor names #{editor}, but the project declares no Editor row" if setting.nil?
 
-          options = { domain_chapter: domain_chapter(project, setting), table: site.table }
-          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options)
+          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options(project, setting, site))
           files.to_h { |name, text| [File.join(File.expand_path(editor), name), text] }
         rescue ArgumentError, Projections::Site::Table::Invalid => e
           abort "project_site: #{e.message}"
         end
 
+        # @return [Hash{Symbol => Object}] the chapters the editor reads, and the route table
+        def options(project, setting, site)
+          chosen = { domain_chapters: setting.chapters.map { |name| domain_chapter(project, setting, name) }, table: site.table }
+          chosen[:media_chapter] = domain_chapter(project, setting, setting.media_chapter) if setting.media_chapter
+          chosen
+        end
+
+        # @param name [String] the chapter to find; the row's first `chapter` unless given
         # @return [Bluebook::Chapter] the chapter the `Editor` row names, from its domain directory
-        def domain_chapter(project, setting)
+        def domain_chapter(project, setting, name = setting.chapter)
           domain_root = File.join(project, setting.domain)
-          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == setting.chapter }
-          abort "project_site: #{domain_root} declares no chapter #{setting.chapter}" unless chapter
+          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == name }
+          abort "project_site: #{domain_root} declares no chapter #{name}" unless chapter
           chapter
         end
       end

data/lib/hecks/tools/tenant_provisioning.rb

@@ -80,7 +80,7 @@ module Hecks
       # @raise [SystemExit] when the declared shape is refused, or provisioning is refused
       def provision(slug, options, domain_directory)
         lib_hecks  = File.expand_path("..", __dir__)
-        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_doors: false)
+        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
         provision_tenant(dispatcher, slug, tenant_facts(slug, options, domain_directory))
         refuse_if_refused(dispatcher, slug)
 
@@ -126,7 +126,7 @@ module Hecks
       # @return [void]
       # @raise [SystemExit] when the tenant was never registered in Tenancy
       def confirm(dispatcher, slug, options, domain_directory)
-        target = Hecks.boot(domain_directory, environment: slug, install_doors: false)
+        target = Hecks.boot(domain_directory, environment: slug, install_driving: false)
         puts "booted #{options[:domain]} for tenant #{slug.inspect} under realm #{options[:realm].inspect}"
 
         refuse_unless_tenant_capable(target.registry)

data/lib/hecks/tools/tools_doc.rb

@@ -177,7 +177,7 @@ module Hecks
       class Context
         # @param root [String] the checkout
         def initialize(root)
-          @runtime = Hecks.boot(File.join(root, "lib/hecks/hecks"), install_doors: false)
+          @runtime = Hecks.boot(File.join(root, "lib/hecks/hecks"), install_driving: false)
           @projections = {}
         end
 
@@ -201,8 +201,8 @@ module Hecks
 
         def projection(chapter)
           @projections[chapter] ||= begin
-            launcher = Doors::LauncherOptions.settings(@runtime, chapter)
-            options = Doors::LauncherOptions.projection(launcher, "hecks")
+            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, chapter)
+            options = Adapters::Driving::LauncherOptions.projection(launcher, "hecks")
             Projector.call(:cli, bluebook: @runtime.registry.bluebook(chapter), options: options)
           end
         end
@@ -210,7 +210,7 @@ module Hecks
         # `hecks ir`, `hecks console`, `hecks quality_control sweep.run`, `hecks host.check_era`.
         # The launcher takes a name that is only a query as a query, so no `query` word is needed.
         def words(chapter, name, row)
-          route = route_for(Doors::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
+          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
           return [route] if route
 
           [*(Naming.snake(chapter) unless chapter == "Hecks"), name]

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.10.0".freeze
+  VERSION = "3.12.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,6 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"before_sha", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
+        {"name"=>"release_only", "workflow"=>"ci.yml", "mode"=>"release_only", "pattern"=>"", "push"=>"before_sha", "label"=>"is this change only a release bump on a certified base?"}.freeze,
         {"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)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"skip", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
@@ -107,8 +108,8 @@ module Hecks
         {"type"=>"String", "strategy"=>"substring"}.freeze
       ].freeze,
       "Lane" => [
-        {"name"=>"main", "guarded"=>"no", "pushers"=>"anyone", "feeds"=>"", "follows"=>"", "alert_after"=>""}.freeze,
-        {"name"=>"stable", "guarded"=>"yes", "pushers"=>"green", "feeds"=>"edge", "follows"=>"main", "alert_after"=>"4"}.freeze
+        {"name"=>"main", "guarded"=>"no", "pushers"=>"anyone", "feeds"=>"", "follows"=>"", "alert_after"=>"", "release_trailer"=>""}.freeze,
+        {"name"=>"stable", "guarded"=>"yes", "pushers"=>"green", "feeds"=>"edge", "follows"=>"main", "alert_after"=>"4", "release_trailer"=>"Release-Approved-By"}.freeze
       ].freeze,
       "LoadOrder" => [
         {"glob"=>"*.port"}.freeze,
@@ -134,6 +135,9 @@ module Hecks
         {"name"=>"replace"}.freeze,
         {"name"=>"scale_call"}.freeze
       ].freeze,
+      "PrebuiltBinary" => [
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+      ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
         {"name"=>"Integer"}.freeze,
@@ -363,6 +367,15 @@ module Hecks
         {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
         {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
       ].freeze,
+      "ReleaseFile" => [
+        {"path"=>"lib/hecks/version.rb", "lines"=>"^\\s*VERSION = \"[0-9]+\\.[0-9]+\\.[0-9]+\"\\.freeze$"}.freeze,
+        {"path"=>"CHANGELOG.md", "lines"=>""}.freeze,
+        {"path"=>"README.md", "lines"=>"^(\\*\\*Status:\\*\\* )?Current release: `[0-9]+\\.[0-9]+\\.[0-9]+`"}.freeze,
+        {"path"=>"Gemfile.lock", "lines"=>"^    hecks \\([0-9]+\\.[0-9]+\\.[0-9]+\\)$"}.freeze,
+        {"path"=>"rust/host/HECKS_RELEASE", "lines"=>"^[0-9]+\\.[0-9]+\\.[0-9]+$"}.freeze,
+        {"path"=>"packages/hecks-client/package.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze,
+        {"path"=>"packages/hecks-client/package-lock.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze
+      ].freeze,
       "RequiredCheck" => [
         {"name"=>"rspec"}.freeze,
         {"name"=>"checks"}.freeze,
@@ -372,7 +385,8 @@ module Hecks
         {"name"=>"rspec_rust_parser"}.freeze,
         {"name"=>"rspec_rust_codegen"}.freeze,
         {"name"=>"rspec_rust_host"}.freeze,
-        {"name"=>"rspec_fuzzing"}.freeze
+        {"name"=>"rspec_fuzzing"}.freeze,
+        {"name"=>"release_consistency", "runs"=>"always"}.freeze
       ].freeze,
       "RetiredScript" => [
         {"script"=>"ir", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"ir"}.freeze,
@@ -402,8 +416,8 @@ module Hecks
         {"script"=>"compact", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"compact"}.freeze,
         {"script"=>"heki_compact", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"compact_heki"}.freeze,
         {"script"=>"vendor_bluebook", "section"=>"Custodian", "aggregate"=>"Package", "verb"=>"vendor", "note"=>"waits: a refusal exits 1 with its reason on stderr"}.freeze,
-        {"script"=>"project_cli", "section"=>"Custodian", "aggregate"=>"Door", "verb"=>"project_cli"}.freeze,
-        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Door", "verb"=>"serve_mcp"}.freeze,
+        {"script"=>"project_cli", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"project_cli"}.freeze,
+        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"serve_mcp"}.freeze,
         {"script"=>"project_rust", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"project_rust"}.freeze,
         {"script"=>"project_wasm", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_wasm"}.freeze,
         {"script"=>"project_host", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_host"}.freeze,

data/lib/hecks.rb

@@ -12,7 +12,7 @@ require_relative "hecks/construct"
 # extends this to declare what it emits.
 require_relative "hecks/ir"
 require_relative "hecks/literal"
-require_relative "hecks/doors"
+require_relative "hecks/adapters/driving"
 require_relative "hecks/query_specification"
 
 require_relative "hecks/ports"
@@ -27,13 +27,13 @@ require_relative "hecks/projector"
 # installation of them.
 require_relative "hecks/projections"
 # After `Projector`, which dispatches against the `:cli` projection.
-require_relative "hecks/doors/cli_door"
-require_relative "hecks/doors/usage_cache"
-require_relative "hecks/doors/cli_runner"
+require_relative "hecks/adapters/driving/cli"
+require_relative "hecks/adapters/driving/usage_cache"
+require_relative "hecks/adapters/driving/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"
-require_relative "hecks/doors/mcp_door_scope"
-require_relative "hecks/doors/mcp_guide_cache"
+require_relative "hecks/adapters/driving/mcp_scope"
+require_relative "hecks/adapters/driving/mcp_guide_cache"
 require_relative "hecks/framework"
 require_relative "hecks/vendoring"
 require_relative "hecks/embryonaut_bluebook"
@@ -56,12 +56,12 @@ module Hecks
     # the `HECKS_ENVIRONMENT` variable; pass a name to choose one, or `nil` for none.
     # @param path [String] path to a domain directory, or a file inside one
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot`
-    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @param environment [String, nil] env name; its `.hecksagon`/`.world` overlay,
     #   if present, loads after the domain's own. Defaults to `HECKS_ENVIRONMENT`; nil loads none
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot(path, shared: nil, install_doors: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot(path, shared: shared, install_doors: install_doors, environment: environment)
+    def boot(path, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot(path, shared: shared, install_driving: install_driving, environment: environment)
     end
 
     # Loads a domain's declarations without binding any adapter or opening any store.
@@ -78,10 +78,10 @@ module Hecks
     # once. See `Runtime::Loader.boot_described`.
     #
     # @param described [Runtime::Loader::Described] what `describe` answered
-    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot_described(described, install_doors: true)
-      Runtime.boot_described(described, install_doors: install_doors)
+    def boot_described(described, install_driving: true)
+      Runtime.boot_described(described, install_driving: install_driving)
     end
 
     # Boots a domain from an explicit list of files (a `.bluebook`, its
@@ -89,11 +89,11 @@ module Hecks
     # see `Runtime::Loader.boot_files` for why this exists beside `boot`.
     # @param paths [String, Array<String>] one or more file paths within the domain
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot_files`
-    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @param environment [String, nil] environment name passed to the selected-file loader
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot_files(paths, shared: nil, install_doors: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot_files(paths, shared: shared, install_doors: install_doors, environment: environment)
+    def boot_files(paths, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
     end
 
     # Binds the ambient registry for the duration of the block.

data/lib/rubocop/cop/hecks/env_dump.rb

@@ -0,0 +1,69 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a secret leaving the process in output: the whole environment printed, or a
+      # `*_KEY` / `*_SECRET` / `*_TOKEN` / `*_PASSWORD` variable interpolated into a string.
+      #
+      # An interpolated secret ends up in a log line, a failure message or a command line. Reading
+      # one into a local (or an HTTP header) is fine; building a string around it is not. Restoring
+      # the environment in a spec (`saved = ENV.to_h`) is not output, so it is left alone.
+      #
+      # @example
+      #   puts ENV.to_h                                  # bad
+      #   warn "using #{ENV.fetch("API_TOKEN")}"         # bad
+      #   headers["Authorization"] = ENV.fetch("API_TOKEN")  # good
+      class EnvDump < Base
+        MSG_DUMP = "This prints the whole environment, which carries every secret the process holds. " \
+                   "Print only the variable names you need.".freeze
+        MSG_SECRET = "`%<read>s` is a secret read into a string, so it will land in a log line or a message. " \
+                     "Pass it straight to the call that needs it instead of interpolating it.".freeze
+
+        OUTPUT_CALLS = %i[puts p pp print warn].freeze
+        SECRET_NAME = /(KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL)/i
+
+        # @!method whole_env?(node)
+        def_node_matcher :whole_env?, <<~PATTERN
+          {(const {nil? cbase} :ENV) (send (const {nil? cbase} :ENV) {:to_h :to_a :to_s :inspect})}
+        PATTERN
+
+        # @!method env_read(node)
+        def_node_matcher :env_read, <<~PATTERN
+          (send (const {nil? cbase} :ENV) {:[] :fetch} (str $_) ...)
+        PATTERN
+
+        # Flags the whole environment handed to an output call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless node.receiver.nil? && OUTPUT_CALLS.include?(node.method_name)
+          return unless node.arguments.any? { |argument| whole_env?(argument) }
+
+          add_offense(node, message: MSG_DUMP)
+        end
+
+        # Flags a secret variable interpolated into a string.
+        #
+        # @param node [RuboCop::AST::BeginNode] the `#{}` part being visited
+        # @return [void]
+        def on_begin(node)
+          return unless interpolation?(node)
+
+          read = node.children.filter_map { |child| secret_read(child) }.first
+          add_offense(node, message: format(MSG_SECRET, read: read)) if read
+        end
+
+        private
+
+        def interpolation?(node)
+          %i[dstr dsym xstr].include?(node.parent&.type)
+        end
+
+        def secret_read(node)
+          name = env_read(node)
+          node.source if name&.match?(SECRET_NAME)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/monotonic_duration.rb

@@ -0,0 +1,53 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a duration measured as `Time.now - start`, where `start` was read from the clock.
+      #
+      # The wall clock steps when it is corrected, so a subtraction can go negative or jump.
+      # Elapsed time comes from the monotonic clock. `Time.now - seconds` (a past timestamp)
+      # and `Time.now - File.mtime(path)` (an age against a stored time) are left alone.
+      #
+      # @example
+      #   started = Time.now
+      #   elapsed = Time.now - started                                         # bad
+      #
+      #   started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      #   elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started  # good
+      class MonotonicDuration < Base
+        MSG = "`Time.now - %<start>s` measures elapsed time on the wall clock, which can step. " \
+              "Take both ends from `Process.clock_gettime(Process::CLOCK_MONOTONIC)`.".freeze
+
+        # @!method wall_clock_minus_variable(node)
+        def_node_matcher :wall_clock_minus_variable, <<~PATTERN
+          (send #clock_read? :- ${lvar ivar})
+        PATTERN
+
+        # @!method clock_read?(node)
+        def_node_matcher :clock_read?, <<~PATTERN
+          {(send (const {nil? cbase} :Time) :now) (send (send (const {nil? cbase} :Time) :now) :to_f)}
+        PATTERN
+
+        # Flags `Time.now - <variable>` when the variable holds an earlier clock read.
+        #
+        # @param node [RuboCop::AST::SendNode] the subtraction being visited
+        # @return [void]
+        def on_send(node)
+          start = wall_clock_minus_variable(node)
+          return unless start && assigned_from_clock?(node, start)
+
+          add_offense(node, message: format(MSG, start: start.source))
+        end
+
+        private
+
+        # Whether the variable is assigned a clock read anywhere in the enclosing method or class.
+        def assigned_from_clock?(node, variable)
+          scope = node.each_ancestor(:def, :defs, :class, :module).first || processed_source.ast
+          scope.each_descendant(:lvasgn, :ivasgn).any? do |assignment|
+            assignment.name == variable.children.first && clock_read?(assignment.expression)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/no_wall_clock_in_runtime.rb

@@ -0,0 +1,34 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a direct wall-clock read (`Time.now`, `Date.today`, `Time.current`) in the runtime.
+      #
+      # The runtime must stay replayable (ADR 0081), so time reaches a command through `needs :now`
+      # or through the one stamping seam, `Hecks::Runtime::Event.stamp`; a stray read makes a
+      # replay differ from the original run and cannot be pinned in a test.
+      #
+      # @example
+      #   Event.new(name: n, occurred_at: Time.now.utc.iso8601)  # bad
+      #   Event.new(name: n, occurred_at: Event.stamp)           # good
+      class NoWallClockInRuntime < Base
+        MSG = "`%<call>s` reads the wall clock inside the runtime, so a replay cannot reproduce it. " \
+              "Declare `needs :now` on the command, or stamp an event with `Hecks::Runtime::Event.stamp`.".freeze
+
+        # @!method wall_clock_read?(node)
+        def_node_matcher :wall_clock_read?, <<~PATTERN
+          (send (const {nil? cbase} {:Time :Date :DateTime}) {:now :today :current})
+        PATTERN
+
+        # Flags a `Time.now`-style call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless wall_clock_read?(node)
+
+          add_offense(node, message: format(MSG, call: node.source))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/raw_shell_interpolation.rb

@@ -0,0 +1,79 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a shell command built by interpolating a value into one string.
+      #
+      # `system("rm -rf #{dir}")` hands the shell a string it re-parses, so a value with a space
+      # or a metacharacter changes the command. The array form (`system("rm", "-rf", dir)`)
+      # passes each argument as-is. An interpolation wrapped in `Shellwords.escape` or
+      # `shellescape` is left alone.
+      #
+      # @example
+      #   system("git checkout #{branch}")         # bad
+      #   system("git", "checkout", branch)        # good
+      class RawShellInterpolation < Base
+        MSG = "`%<call>s` runs a string with `\#{}` interpolated into it, so the shell re-parses the value. " \
+              "Pass the command as separate arguments (`%<call>s(\"cmd\", arg)`), or wrap the value in " \
+              "`Shellwords.escape`.".freeze
+
+        XSTR_MSG = "A backtick or `%x` command with `\#{}` interpolated into it is re-parsed by the shell. " \
+                   "Use `IO.popen([\"cmd\", arg], &:read)` or `Open3.capture2(\"cmd\", arg)`, or wrap the " \
+                   "value in `Shellwords.escape`.".freeze
+
+        SHELL_CALLS = %i[system exec spawn].freeze
+        OPEN3_CALLS = %i[capture2 capture2e capture3 popen2 popen2e popen3 pipeline pipeline_r pipeline_w
+                         pipeline_rw pipeline_start].freeze
+
+        # @!method open3_receiver?(node)
+        def_node_matcher :open3_receiver?, "(const {nil? cbase} :Open3)"
+
+        # @!method escaped?(node)
+        def_node_matcher :escaped?, <<~PATTERN
+          {(send (const {nil? cbase} :Shellwords) {:escape :shellescape :join :shelljoin} ...)
+           (send _ {:shellescape :shelljoin})}
+        PATTERN
+
+        # Flags a single-string command with a raw interpolation.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless shell_call?(node)
+
+          command = command_argument(node)
+          return unless command&.dstr_type? && raw_interpolation?(command)
+
+          add_offense(node, message: format(MSG, call: node.method_name))
+        end
+
+        # Flags a backtick or `%x` literal with a raw interpolation.
+        #
+        # @param node [RuboCop::AST::StrNode] the command literal being visited
+        # @return [void]
+        def on_xstr(node)
+          return unless raw_interpolation?(node)
+
+          add_offense(node, message: XSTR_MSG)
+        end
+
+        private
+
+        def shell_call?(node)
+          return SHELL_CALLS.include?(node.method_name) if node.receiver.nil? || node.receiver.cbase_type?
+
+          open3_receiver?(node.receiver) && OPEN3_CALLS.include?(node.method_name)
+        end
+
+        # The lone command string, after an optional leading env hash; nil when it passes argv.
+        def command_argument(node)
+          args = node.arguments.drop_while(&:hash_type?)
+          args.first if args.size == 1
+        end
+
+        def raw_interpolation?(node)
+          node.each_child_node(:begin).any? { |part| !escaped?(part.children.first) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/sleep_in_spec.rb

@@ -0,0 +1,34 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a fixed `sleep` in a spec.
+      #
+      # A fixed sleep is a guess about how long another thread needs: too short and the example is
+      # flaky, too long and the suite is slow. Wait on the thing itself instead, with a Queue, a
+      # latch, or `ThreadParking.wait_until_parked(thread)` when the assertion is "still blocked".
+      #
+      # @example
+      #   sleep 0.2                                   # bad
+      #   ThreadParking.wait_until_parked(waiter)     # good
+      class SleepInSpec < Base
+        MSG = "A fixed `sleep` guesses how long another thread needs, so the example is either flaky or " \
+              "slow. Wait on the thread itself: a Queue, or `ThreadParking.wait_until_parked(thread)`.".freeze
+
+        RESTRICT_ON_SEND = %i[sleep].freeze
+
+        # @!method fixed_sleep?(node)
+        def_node_matcher :fixed_sleep?, <<~PATTERN
+          (send {nil? (const {nil? cbase} :Kernel)} :sleep ...)
+        PATTERN
+
+        # Flags a `sleep` call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          add_offense(node, message: MSG) if fixed_sleep?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/swallowed_rescue.rb

@@ -0,0 +1,37 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a broad `rescue` whose whole body is `nil`, `false` or `next`.
+      #
+      # A bare `rescue` or `rescue StandardError` that answers a literal turns any crash into an
+      # ordinary "no result". Rescuing a named error is left alone; a deliberate guard goes
+      # through `Hecks::Runtime::BestEffort.call(default) { ... }`.
+      #
+      # @example
+      #   adapter.capable? rescue false                           # bad
+      #   BestEffort.call(false) { adapter.capable? }             # good
+      class SwallowedRescue < Base
+        MSG = "This broad `rescue` answers `%<answer>s` for any failure, so a crash reads as an ordinary " \
+              "\"no result\". Rescue the specific error, or use `Runtime::BestEffort.call(default) { ... }` " \
+              "for a deliberate guard.".freeze
+
+        # @!method swallowed_answer(node)
+        def_node_matcher :swallowed_answer, <<~PATTERN
+          (resbody {nil? (array (const {nil? cbase} {:StandardError :Exception}))} _
+            ${(nil) (false) (next)})
+        PATTERN
+
+        # Flags a broad rescue clause that answers a bare literal.
+        #
+        # @param node [RuboCop::AST::ResbodyNode] the rescue clause being visited
+        # @return [void]
+        def on_resbody(node)
+          answer = swallowed_answer(node)
+          return unless answer
+
+          add_offense(node, message: format(MSG, answer: answer.source))
+        end
+      end
+    end
+  end
+end