hecks 3.2.0 → 3.3.0

data/lib/hecks/tools/rust_comment_style.rb

@@ -30,7 +30,7 @@ module Hecks
       DOC_LINE = %r{\A\s*(?:///(?!/)|//!)}
 
       # `// TMPL:name BEGIN`/`END` sentinels are parsed verbatim by
-      # `rust/project/exemplar.rb`; every prose rule skips them outright.
+      # `rust/codegen/src/exemplar.rs`; every prose rule skips them outright.
       TMPL_MARKER = /\bTMPL:\S+\s+(?:BEGIN|END)\b/i
       MOD_DOC_LINE = %r{\A\s*//!}
       ATTR_LINE = /\A\s*#\[/
@@ -45,9 +45,7 @@ module Hecks
       # Rust-specific acronyms beyond the Ruby linter's list.
       RUST_ACRONYMS = %w[EOF RAII RHS SQS DLQ JIT LSP NFA DFA CR].to_set.freeze
 
-      RUST_PROPER_NOUNS = {
-        "EMBRYONAUT" => "Embryonaut"
-      }.freeze
+      RUST_PROPER_NOUNS = {}.freeze
 
       RUST_EXTRA_WORDS = %w[
         cardinality routability prepend safer diff diffed stats earliest unbracketed

data/lib/hecks/tools/site_routes.rb

@@ -14,41 +14,47 @@ module Hecks
     # it declares an edge, into the behaviours and listener rules of its template
     # (`Projections::Site::SiteCdn`).
     #
-    #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]
+    #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--template=<file>]
+    #                                           [--extension=ts|mts] [--check]
     #
-    # `<project>` is the directory whose `bluebook/` holds the chapter that declares the rows and a
-    # hecksagon that attaches Site; it defaults to the checkout. `routes.ts` is written to
-    # `<project>/generated` unless `--out` names another directory. The template is rewritten in
-    # place between its `BEGIN`/`END GENERATED site_cdn` markers, or under `--out` a copy of it is
-    # written at the same relative path. With `--check` nothing is written: the tool answers 1 and
-    # names each file that differs from the table.
+    # `<project>` (default: the working directory) holds `bluebook/` and the `vendor/` it attaches
+    # from. `routes.ts` goes to `<project>/generated` or to `--out`, anywhere. The template is the
+    # `Edge` row's, relative to the project, or `--template`, anywhere; it is rewritten in place
+    # between its `BEGIN`/`END GENERATED site_cdn` markers. With `--out` alone, `--out` receives a
+    # copy of it instead. `--extension=mts` names the module `routes.mts`; `--check` writes nothing.
     module SiteRoutes
       # Where the files go, relative to the project, when `--out` names no directory.
       DEFAULT_OUT = "generated"
 
-      USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]"
+      # The extensions the module may take; the first is the default.
+      EXTENSIONS = %w[ts mts].freeze
+
+      USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
+              "[--template=<file>] [--extension=#{EXTENSIONS.join('|')}] [--check]".freeze
 
       module_function
 
       # Projects the route table, writes what differs and prints a line for each file written.
       #
       # @param argv [Array<String>] the project directory, then the flags
-      # @param root [String] the checkout, used as the project when `argv` names none
+      # @param root [String] the project used when `argv` names none; the working directory
       # @return [Integer] 0, or 1 when `--check` finds a file out of date
-      # @raise [SystemExit] with the reason on stderr when the project declares no route table or
-      #   the table is refused
-      def main(argv, root: Tools::ROOT)
+      # @raise [SystemExit] with the reason on stderr when the project declares no route table, the
+      #   table is refused, or a flag is refused
+      def main(argv, root: Dir.pwd)
         argv = argv.dup
-        out = nil
+        out = template = extension = nil
         check = false
         OptionParser.new do |parser|
           parser.on("--out=DIR") { |value| out = value }
+          parser.on("--template=FILE") { |value| template = value }
+          parser.on("--extension=EXT") { |value| extension = value }
           parser.on("--check") { check = true }
         end.parse!(argv)
         project = argv.empty? ? root : File.expand_path(argv.shift)
         abort USAGE unless argv.empty?
 
-        files = projection(project, out: out)
+        files = projection(project, out: out, template: template, extension: extension)
         stale = files.reject { |path, text| File.file?(path) && File.read(path) == text }.keys
         return report(stale, project, check) if check
 
@@ -63,16 +69,26 @@ module Hecks
 
       # @param root [String] the project directory
       # @param out [String, nil] the directory to write to; `generated/` of the project when nil
+      # @param template [String, nil] the template to rewrite in place, wherever it lies; the
+      #   `Edge` row's template, relative to the project, when nil
+      # @param extension [String, nil] `ts` (the default) or `mts`, the module's file extension
       # @return [Hash{String => String}] each file's absolute path to the text it should hold
-      # @raise [SystemExit] when the project declares no route table or the table is refused
-      def projection(root, out: nil)
+      # @raise [SystemExit] when the project declares no route table, the table is refused, or a
+      #   path or the extension is refused
+      def projection(root, out: nil, template: nil, extension: nil)
+        extension ||= EXTENSIONS.first
+        unless EXTENSIONS.include?(extension)
+          abort "project_site: --extension is one of #{EXTENSIONS.join(', ')}, not #{extension.inspect}"
+        end
+        dir = out ? File.expand_path(out) : File.join(root, DEFAULT_OUT)
+        abort "project_site: --out #{dir} is a file; it names the directory routes.#{extension} goes in" if File.file?(dir)
+
         registry = registry_for(root)
         chapter = Projections::Site::Table.chapter(registry)
         table = Projections::Site::Table.read(chapter, registry: registry)
         files = Projector.call(:site_routes_ts, bluebook: chapter, options: { table: table })
-        dir = out ? File.expand_path(out) : File.join(root, DEFAULT_OUT)
-        written = files.to_h { |name, text| [File.join(dir, name), text] }
-        written.merge(template_files(root, out, chapter, table, registry))
+        written = files.to_h { |name, text| [File.join(dir, name.sub(/\.ts\z/, ".#{extension}")), text] }
+        written.merge(template_files(root, out, chapter, table, registry, template: template))
       rescue Projections::Site::Table::Invalid => e
         abort "project_site: #{e.message}"
       end
@@ -84,25 +100,50 @@ module Hecks
       # @param chapter [Bluebook::Chapter] the chapter that declares the route table
       # @param table [Projections::Site::Table] the checked table
       # @param registry [Hecks::Runtime::Registry] the registry the project booted into
+      # @param template [String, nil] a template named on the command line, rewritten in place
       # @return [Hash{String => String}] the template's path to its text; empty with no edge
-      # @raise [SystemExit] when the template is missing or lacks a region
-      def template_files(root, out, chapter, table, registry)
-        edge = Projections::Site::Edge.read(chapter, table: table, vocabulary: Projections::Site::Table.vocabulary(registry))
-        return {} unless edge
+      # @raise [SystemExit] when a template is named and the project declares no edge, the
+      #   template is missing or lacks a region it needs, or holds a region an edge without a load
+      #   balancer does not use
+      def template_files(root, out, chapter, table, registry, template: nil)
+        edge = Projections::Site::Edge.read(chapter, table: table, template: template,
+                                                     vocabulary: Projections::Site::Table.vocabulary(registry))
+        unless edge
+          abort "project_site: --template names #{template}, but the project declares no Edge rows" if template
+          return {}
+        end
 
         regions = Projector.call(:site_cdn, bluebook: chapter, options: { table: table, edge: edge })
-        relative = edge.setting.template
-        source = File.join(root, relative)
-        abort "project_site: the template #{relative} does not exist in #{root}" unless File.file?(source)
+        relative = template || edge.setting.template
+        source = template ? File.expand_path(template) : File.join(root, relative)
+        unless File.file?(source)
+          abort "project_site: the template #{relative} does not exist#{" in #{root}" unless template}"
+        end
 
-        text = regions.reduce(File.read(source)) do |current, (name, block)|
+        text = rewritten(File.read(source), regions, relative, edge)
+        in_place = template || out.nil?
+        { (in_place ? source : File.join(File.expand_path(out), relative)) => text }
+      end
+
+      # @param text [String] the template
+      # @param regions [Hash{String => String}] each region's name to the block that goes in it
+      # @param relative [String] the template's name, for a message
+      # @param edge [Projections::Site::Edge] the checked edge
+      # @return [String] the template with each region rewritten
+      # @raise [SystemExit] when a region is missing, or a listener_rules region is left behind
+      #   by an edge with no load balancer
+      def rewritten(text, regions, relative, edge)
+        if !edge.alb? && Projections::Site::Regions.region?(text, "listener_rules")
+          abort "project_site: #{relative} has a BEGIN/END GENERATED site_cdn listener_rules region, " \
+                "and the Edge row says alb: false; remove the region"
+        end
+        regions.reduce(text) do |current, (name, block)|
           unless Projections::Site::Regions.region?(current, name)
             abort "project_site: #{relative} has no BEGIN/END GENERATED site_cdn #{name} region"
           end
 
           Projections::Site::Regions.replace(current, name, block)
         end
-        { (out ? File.join(File.expand_path(out), relative) : source) => text }
       end
 
       # Loads the project's chapters the way a deploy does: the bluebooks, then the hecksagons that

data/lib/hecks/tools/tools_doc.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "hecks/vocabulary"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Writes the launcher forms of `docs/tools.md` from the `RetiredScript` rows of the Vocabulary
+    # chapter. Each row names a command (or, in QualityControl, a query); its form is rendered from
+    # that command's own arguments, the same projection the launcher parses against, so a form can
+    # neither keep an argument the command dropped nor miss one it gained.
+    #
+    # Only the tables between the `generated:begin tools` and `generated:end tools` comments are
+    # written; the prose around them is hand-written and left alone. With `--check` nothing is
+    # written: the tool answers 1 and names the sections that differ from the rows.
+    module ToolsDoc
+      # The document, relative to the checkout.
+      DOCUMENT = "docs/tools.md"
+
+      # The sections of the document, in the order it lists them.
+      SECTIONS = %w[Custodian Deploy Site Codebase QualityControl].freeze
+
+      # The first line of a table, and the line that closes it.
+      HEADER = "| launcher | replaces |\n|---|---|"
+
+      module_function
+
+      # @param argv [Array<String>] `--check` to compare without writing
+      # @param root [String] the checkout
+      # @return [Integer] 0, or 1 when `--check` finds a section out of date
+      # @raise [SystemExit] when a section has no marked table
+      def main(argv, root: Tools::ROOT)
+        path = File.join(root, DOCUMENT)
+        text = File.read(path, encoding: "UTF-8")
+        fresh = projection(text, root)
+        return report(text, fresh) if argv.include?("--check")
+
+        File.write(path, fresh, encoding: "UTF-8") unless fresh == text
+        puts(fresh == text ? "tools_doc: #{rows.size} rows, every table current" : "wrote #{DOCUMENT}")
+        0
+      end
+
+      # @return [Array<Hash{String => String}>] the `RetiredScript` rows, in table order
+      def rows = Hecks::Vocabulary.rows("RetiredScript")
+
+      # The launcher form each retired script became, as the table lists it.
+      #
+      # @param root [String] the checkout
+      # @return [Hash{String => String}] script name to its forms, joined with `; `; a command no
+      #   script preceded (`(new)`) has none
+      def forms(root: Tools::ROOT)
+        @forms ||= {}
+        @forms[root] ||= begin
+          context = Context.new(root)
+          rows.reject { |row| row["script"] == "(new)" }.group_by { |row| row["script"] }
+              .transform_values { |group| group.map { |row| form(row, context) }.join("; ") }
+        end
+      end
+
+      # @param text [String] the document as it stands
+      # @param root [String] the checkout
+      # @return [String] the document with each section's table rewritten from the rows
+      # @raise [SystemExit] when a section has no marked table
+      def projection(text, root)
+        context = Context.new(root)
+        SECTIONS.reduce(text) do |held, section|
+          region = /(<!-- generated:begin tools section=#{section} -->\n).*?(<!-- generated:end tools -->)/m
+          abort "tools_doc: #{DOCUMENT} has no marked table for #{section}" unless held.match?(region)
+
+          held.sub(region) { "#{Regexp.last_match(1)}#{table(section, context)}\n#{Regexp.last_match(2)}" }
+        end
+      end
+
+      # @param section [String] one of `SECTIONS`
+      # @param context [Context] the booted chapters
+      # @return [String] the section's table, header included
+      def table(section, context)
+        lines = rows.select { |row| row["section"] == section }.group_by { |row| row["script"] }.map do |script, group|
+          cell = group.map { |row| cell(row, context) }.join("; ")
+          "| #{cell} | #{script == '(new)' ? '(new: no `bin/` script)' : "`bin/#{script}`"} |"
+        end
+        [HEADER, *lines].join("\n")
+      end
+
+      # One form as the table shows it: in backticks, with a `|` escaped.
+      def cell(row, context) = "`#{form(row, context).gsub('|', '\|')}`"
+
+      # @param row [Hash{String => String}] a `RetiredScript` row
+      # @param context [Context] the booted chapters
+      # @return [String] the launcher form of the row's command or query
+      def form(row, context)
+        return row["form"] unless row["form"].to_s.empty?
+
+        spec, words = context.spec_for(row)
+        passes = row["passes"].to_s
+        text = [*words, *argument_words(spec, skip: passes.empty? ? [] : %w[arguments])].join(" ")
+        text += %( [arguments="#{passes}"]) unless passes.empty?
+        text += " (#{row['note']})" unless row["note"].to_s.empty?
+        "hecks #{text}"
+      end
+
+      # The words after the verb: the first argument bare, the rest `name=`, flags last.
+      #
+      # @param spec [Hash] a projected command or query
+      # @param skip [Array<String>] arguments not to spell, because the row documents them itself
+      # @return [Array<String>] each argument as the launcher spells it
+      def argument_words(spec, skip: [])
+        named = by_attribute(spec[:arguments].reject do |argument|
+          argument[:minted] || skip.include?(argument[:path].split(".").first)
+        end)
+        # The launcher reads a bare word as the first argument, when that is not a flag.
+        bare = named.first unless named.empty? || named.first[:type] == "Boolean"
+        flags, plain = (named - [bare].compact).partition { |argument| argument[:type] == "Boolean" }
+        [*(bracket(bare, "<#{bare[:path]}>") if bare),
+         *plain.map { |argument| bracket(argument, "#{argument[:path]}=") },
+         *flags.map { |argument| flag_word(argument) }]
+      end
+
+      # A one-field value object's `x.value` leaf is spelled as the attribute, `x`; a value object
+      # with more fields keeps one leaf each.
+      #
+      # @param leaves [Array<Hash>] projected leaf arguments
+      # @return [Array<Hash>] the arguments the launcher takes, one per attribute for a scalar
+      def by_attribute(leaves)
+        leaves.group_by { |argument| argument[:path].split(".").first }.flat_map do |head, group|
+          group.size == 1 && group.first[:path].end_with?(".value") ? [group.first.merge(path: head)] : group
+        end
+      end
+
+      # @param argument [Hash] a projected argument
+      # @param word [String] how it is spelled
+      # @return [String] `word`, in brackets when the argument is optional
+      def bracket(argument, word) = argument[:required] ? word : "[#{word}]"
+
+      # `--confirm` is what makes a verb act, so it stands bare; any other flag is optional.
+      def flag_word(argument)
+        word = "--#{argument[:path].tr('_', '-')}"
+        argument[:path] == "confirm" ? word : "[#{word}]"
+      end
+
+      # @param text [String] the document as it stands
+      # @param fresh [String] the document the rows give
+      # @return [Integer] 0 when current, else 1 with the stale sections on stderr
+      def report(text, fresh)
+        return 0 if text == fresh
+
+        stale = SECTIONS.reject { |section| section_text(text, section) == section_text(fresh, section) }
+        warn "tools_doc: #{DOCUMENT} differs from the RetiredScript rows in: #{stale.join(', ')} " \
+             "(run hecks regeneration_run.project_tools_doc --confirm)"
+        1
+      end
+
+      # @return [String, nil] the marked table of one section
+      def section_text(text, section)
+        text[/<!-- generated:begin tools section=#{section} -->\n(.*?)<!-- generated:end tools -->/m, 1]
+      end
+
+      # The booted Hecks chapters the forms are rendered from, built once.
+      class Context
+        # @param root [String] the checkout
+        def initialize(root)
+          @runtime = Hecks.boot(File.join(root, "lib/hecks/hecks"), install_doors: false)
+          @projections = {}
+        end
+
+        # @param row [Hash{String => String}] a `RetiredScript` row
+        # @return [Array(Hash, Array<String>)] the projected command or query, and the words that
+        #   name it on the command line
+        # @raise [SystemExit] when the row names no command or query
+        def spec_for(row)
+          chapter = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
+          cli = projection(chapter)
+          name = "#{Naming.snake(row['aggregate'])}.#{row['verb']}"
+          command = cli[:commands][cli[:names][:command][name]]
+          question = cli[:questions][cli[:names][:question][name]]
+          spec = command || question or abort "tools_doc: #{chapter} has no command or query #{name}"
+          [spec, words(chapter, name, row)]
+        end
+
+        private
+
+        def projection(chapter)
+          @projections[chapter] ||= begin
+            launcher = Doors::LauncherOptions.settings(@runtime, chapter)
+            options = Doors::LauncherOptions.projection(launcher, "hecks")
+            Projector.call(:cli, bluebook: @runtime.registry.bluebook(chapter), options: options)
+          end
+        end
+
+        # `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)
+          settings = Doors::LauncherOptions.settings(@runtime, chapter) || {}
+          route = (settings[:names] || {}).key(name)
+          route ||= row["verb"] if chapter == "Hecks" && Array(settings[:legacy]).include?(row["verb"])
+          return [route] if route
+
+          [*(Naming.snake(chapter) unless chapter == "Hecks"), name]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools.rb

@@ -23,6 +23,7 @@ module Hecks
       "argument_gate_matrix"           => ["tools/argument_gate_matrix", "ArgumentGateMatrix"],
       "project_ci_gates"               => ["tools/ci_gates", "CiGates"],
       "decide_ci_gate"                 => ["tools/ci_gate_decision", "CiGateDecision"],
+      "project_tools_doc"              => ["tools/tools_doc", "ToolsDoc"],
       "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
       "project_site"                   => ["tools/site_routes", "SiteRoutes"],
       "lint_deploy_recipes"            => ["tools/deploy_recipe_lint", "DeployRecipeLint"],

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.2.0".freeze
+  VERSION = "3.3.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,7 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"skip", "label"=>"does this change touch lib/hecks/runtime/**?"}.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|project)/|rust/project\\.rb$|rust/project_rust_pipeline\\.rb$|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.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"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
         {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,
@@ -137,6 +137,34 @@ module Hecks
         {"name"=>"TrueClass"}.freeze,
         {"name"=>"FalseClass"}.freeze
       ].freeze,
+      "QaDial" => [
+        {"name"=>"cadence_seconds", "type"=>"Integer", "meaning"=>"Minimum gap in seconds between one tick's report and the next dispatch; 0 is immediately. Read by the `/loop hecks_qa` caller, not by any script."}.freeze,
+        {"name"=>"pr_cap_per_day", "type"=>"Integer", "meaning"=>"Most PRs (Patch plus Improvement) `hecks quality_control patch.open` opens per calendar day; 0 is uncapped."}.freeze,
+        {"name"=>"widening_tiers", "type"=>"Array", "meaning"=>"Fuzz depth by `Target.clean_streak`, in three discrete tiers, read by `SweepDepth.for_streak`. The last row (`upto: Float::INFINITY`) is the ceiling."}.freeze,
+        {"name"=>"sweep_max_parallel", "type"=>"Integer", "meaning"=>"How many `hecks quality_control query sweep.run <target>` children `--all` keeps running at once."}.freeze,
+        {"name"=>"liveness_fallback_seconds", "type"=>"Integer", "meaning"=>"How long the `/loop hecks_qa` caller waits for a tick's report before assuming it stalled."}.freeze,
+        {"name"=>"draft_only", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control patch.open` opens its PR as a draft; false opens it ready for review."}.freeze,
+        {"name"=>"auto_merge", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control patch.open` queues the PR for auto-merge once it is open."}.freeze,
+        {"name"=>"adversarial_fraction", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of generated command steps mutated adversarially; 0 turns the layer off. Higher finds refusal-ordering splits sooner but reaches deep state less often."}.freeze,
+        {"name"=>"guided_generation", "type"=>"Boolean", "meaning"=>"Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`)."}.freeze,
+        {"name"=>"corpus_splice_probability", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."}.freeze,
+        {"name"=>"favor_rare_verbs", "type"=>"Integer", "meaning"=>"How many of the least-hit verbs the next seed weights up; 0 turns the lever off."}.freeze,
+        {"name"=>"self_consistency_checks", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay idempotency, value-object JSON round trip) on the same generated sequence."}.freeze,
+        {"name"=>"shrink_budget", "type"=>"Integer", "meaning"=>"Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking off. `concurrency` is never shrunk: a race does not reproduce on demand."}.freeze,
+        {"name"=>"yield_weight_seconds", "type"=>"Integer", "meaning"=>"Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`. Zero would make yield invisible, so pick a number that lets it matter."}.freeze,
+        {"name"=>"yield_decay_percent", "type"=>"Integer", "meaning"=>"Percent of the prior yield score kept at each release, so recent findings dominate. Applied by the caller: the mutation language cannot express \"decay, then add\" in `Release`."}.freeze,
+        {"name"=>"rotation_stale_floor_seconds", "type"=>"Integer", "meaning"=>"Once a waiting target is this stale, `RotationPriority.pick` takes it whatever its yield score, so a quiet target cannot starve."}.freeze,
+        {"name"=>"persistence_parity_seed_cap", "type"=>"Integer", "meaning"=>"Ceiling on `--seeds` for `--persistence-parity`, which pays for real Postgres per dispatch. `hecks quality_control query sweep.run` clamps down, never up, and prints a note."}.freeze,
+        {"name"=>"concurrency_seed_cap", "type"=>"Integer", "meaning"=>"Ceiling on `--seeds` for the concurrency mode, which needs two disposable schemas per seed."}.freeze,
+        {"name"=>"adapter_parity_pairs", "type"=>"Hash", "meaning"=>"The two adapters each adapter-parity mode compares, by mode name; a new pairing is a new entry. `adapter_parity_sqlite` needs no `database:`/`schema:` because sqlite has no disposable database."}.freeze,
+        {"name"=>"modes", "type"=>"Hash", "meaning"=>"Which comparison modes `hecks quality_control query sweep.run` may run: the enabled ones intersected with what `TargetCapabilities.infer(path)` finds in the target. `--modes a,b,c` overrides for one run. `wasm_front` and `adapter_parity_postgres` are off because nothing runs them; the others are built and off because their I/O cost across the rotation is unmeasured. `hecks quality_control query sweep.run` refuses to start when a mode outside `TargetCapabilities::RUNNABLE_MODES` is enabled."}.freeze,
+        {"name"=>"role_draw_probability", "type"=>"Numeric", "meaning"=>"How often a generated role-gated command step carries a drawn caller (`role:`/`actor_id:`); 0 turns the draw off."}.freeze,
+        {"name"=>"dry_run_fraction", "type"=>"Numeric", "meaning"=>"Fraction of generated command steps offered as a dry run instead of a real dispatch; 0 is off. Kept low: a dry run creates no state for later steps to act on."}.freeze,
+        {"name"=>"generated_domains_per_tick", "type"=>"Integer", "meaning"=>"How many generated domains one `hecks quality_control sweep.tick` checks after the rotation sweep; 0 skips the step."}.freeze,
+        {"name"=>"generated_domains_rust", "type"=>"Boolean", "meaning"=>"Whether generated domains are also compared against a compiled Rust binary built in a scratch copy."}.freeze,
+        {"name"=>"generated_domain_seeds", "type"=>"Integer", "meaning"=>"Generated sequences run per generated domain."}.freeze,
+        {"name"=>"structural_refusal_boundary", "type"=>"Array", "meaning"=>"Construct families a skipped query verb may belong to. A skip inside the list is logged Held, one outside it Surprised. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails when a family here is declared by no committed manifest."}.freeze
+      ].freeze,
       "QueryComparator" => [
         {"name"=>"eq"}.freeze,
         {"name"=>"ne"}.freeze,
@@ -330,6 +358,129 @@ 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,
+      "RetiredScript" => [
+        {"script"=>"ir", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"ir"}.freeze,
+        {"script"=>"shape", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"shape"}.freeze,
+        {"script"=>"stores", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"stores"}.freeze,
+        {"script"=>"history", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"history"}.freeze,
+        {"script"=>"statements", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"statements"}.freeze,
+        {"script"=>"narrate", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"narrate"}.freeze,
+        {"script"=>"docs", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"docs"}.freeze,
+        {"script"=>"project_diagrams", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"project_diagrams"}.freeze,
+        {"script"=>"project_glossary", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"glossary"}.freeze,
+        {"script"=>"model_check", "section"=>"Custodian", "aggregate"=>"ModelCheckRun", "verb"=>"model_check"}.freeze,
+        {"script"=>"run", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"run", "form"=>"hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"}.freeze,
+        {"script"=>"project", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"refresh_projections"}.freeze,
+        {"script"=>"behaviors", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"run_behaviors"}.freeze,
+        {"script"=>"console", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"open_console"}.freeze,
+        {"script"=>"follow", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"follow"}.freeze,
+        {"script"=>"smoke_test", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"smoke_test"}.freeze,
+        {"script"=>"smoke_http", "section"=>"Custodian", "aggregate"=>"Operation", "verb"=>"smoke_http"}.freeze,
+        {"script"=>"check_era", "section"=>"Custodian", "aggregate"=>"Host", "verb"=>"check_era"}.freeze,
+        {"script"=>"merge_tail", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"merge_tail"}.freeze,
+        {"script"=>"reattest_era", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"reattest"}.freeze,
+        {"script"=>"backfill_era_projections", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"backfill_projections"}.freeze,
+        {"script"=>"scaffold_translation", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"scaffold_translation"}.freeze,
+        {"script"=>"translation_audit", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"audit_translation"}.freeze,
+        {"script"=>"translation_audit", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"approve_translation"}.freeze,
+        {"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_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,
+        {"script"=>"project_wasm_browser", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_browser_wasm"}.freeze,
+        {"script"=>"rust_coverage", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"rust_coverage"}.freeze,
+        {"script"=>"rust_coverage", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"check_coverage_allowlist"}.freeze,
+        {"script"=>"rust_conformance", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"check_conformance"}.freeze,
+        {"script"=>"rust_conformance_fuzz", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"fuzz_conformance"}.freeze,
+        {"script"=>"fuzz", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"fuzz"}.freeze,
+        {"script"=>"generate", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"generate_sequence"}.freeze,
+        {"script"=>"bench", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"bench"}.freeze,
+        {"script"=>"(new)", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"hold_first"}.freeze,
+        {"script"=>"project_deploy", "section"=>"Deploy", "aggregate"=>"Recipe", "verb"=>"project"}.freeze,
+        {"script"=>"lint_deploy_recipes", "section"=>"Deploy", "aggregate"=>"MakefileCheck", "verb"=>"lint"}.freeze,
+        {"script"=>"deploy_template_diff", "section"=>"Deploy", "aggregate"=>"TemplateComparison", "verb"=>"diff"}.freeze,
+        {"script"=>"project_oidc", "section"=>"Deploy", "aggregate"=>"OidcManifest", "verb"=>"project_oidc"}.freeze,
+        {"script"=>"project_tenant", "section"=>"Deploy", "aggregate"=>"Tenant", "verb"=>"provision"}.freeze,
+        {"script"=>"project_tenant", "section"=>"Deploy", "aggregate"=>"Tenant", "verb"=>"reprovision"}.freeze,
+        {"script"=>"(new)", "section"=>"Site", "aggregate"=>"SiteProjection", "verb"=>"project_site"}.freeze,
+        {"script"=>"project_model", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_model"}.freeze,
+        {"script"=>"project_vocabulary", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_vocabulary"}.freeze,
+        {"script"=>"project_rust_vocabulary", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_rust_vocabulary"}.freeze,
+        {"script"=>"project_refusal_wording", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_refusal_wording"}.freeze,
+        {"script"=>"project_reserved_names", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_reserved_names"}.freeze,
+        {"script"=>"project_parser_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_parser_table"}.freeze,
+        {"script"=>"project_bootstrap_table", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_bootstrap_table"}.freeze,
+        {"script"=>"project_field_hints", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_field_hints"}.freeze,
+        {"script"=>"expression_projection", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_expression_tables"}.freeze,
+        {"script"=>"reference", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"project_reference"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"word_status"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"propose"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"admit"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"deprecate"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"retire"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"rename"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"propose_argument"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"admit_argument"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"deprecate_argument"}.freeze,
+        {"script"=>"evolve", "section"=>"Codebase", "aggregate"=>"LanguageRun", "verb"=>"retire_argument"}.freeze,
+        {"script"=>"project_kernel_capabilities", "section"=>"Codebase", "aggregate"=>"KernelRun", "verb"=>"project_kernel_capabilities"}.freeze,
+        {"script"=>"rust_kernel_coverage", "section"=>"Codebase", "aggregate"=>"KernelRun", "verb"=>"measure_kernel_coverage"}.freeze,
+        {"script"=>"check_engine_agreement", "section"=>"Codebase", "aggregate"=>"ConformanceRun", "verb"=>"check_engine_agreement"}.freeze,
+        {"script"=>"doc_coverage", "section"=>"Codebase", "aggregate"=>"ConformanceRun", "verb"=>"measure_doc_coverage"}.freeze,
+        {"script"=>"argument_gate_matrix", "section"=>"Codebase", "aggregate"=>"ConformanceRun", "verb"=>"argument_gate_matrix"}.freeze,
+        {"script"=>"regen_codegen_domains", "section"=>"Codebase", "aggregate"=>"RegenerationRun", "verb"=>"regenerate_corpus"}.freeze,
+        {"script"=>"standardize_comments", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"report_comments"}.freeze,
+        {"script"=>"standardize_comments", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"check_comments"}.freeze,
+        {"script"=>"standardize_comments", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"fix_comments"}.freeze,
+        {"script"=>"standardize_comments", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"write_comment_baseline"}.freeze,
+        {"script"=>"standardize_comments", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"check_comments_unchanged"}.freeze,
+        {"script"=>"standardize_comments_rust", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"report_rust_comments"}.freeze,
+        {"script"=>"standardize_comments_rust", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"check_rust_comments"}.freeze,
+        {"script"=>"standardize_comments_rust", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"fix_rust_comments"}.freeze,
+        {"script"=>"canonicalise", "section"=>"Codebase", "aggregate"=>"StyleRun", "verb"=>"canonicalise"}.freeze,
+        {"script"=>"codemod_hoist_local_givens", "section"=>"Codebase", "aggregate"=>"CodemodRun", "verb"=>"hoist_local_givens"}.freeze,
+        {"script"=>"codemod_implicit_append_fields", "section"=>"Codebase", "aggregate"=>"CodemodRun", "verb"=>"drop_implicit_append_fields"}.freeze,
+        {"script"=>"rspec_shard_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"shard_specs"}.freeze,
+        {"script"=>"rspec_io_parallel_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"list_io_parallel_specs"}.freeze,
+        {"script"=>"rspec_io_parallel_files", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"write_io_parallel_spec_list"}.freeze,
+        {"script"=>"refresh_rspec_runtime_baseline", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"refresh_runtime_baseline"}.freeze,
+        {"script"=>"spec_example", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"run_spec_example"}.freeze,
+        {"script"=>"stress_concurrency_specs", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"stress_concurrency"}.freeze,
+        {"script"=>"regenerate_persistence_legacy_fixtures", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"regenerate_legacy_fixtures"}.freeze,
+        {"script"=>"seed_semantics_corpus", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"seed_semantics_corpus"}.freeze,
+        {"script"=>"pattern-cases", "section"=>"Codebase", "aggregate"=>"TestSuiteRun", "verb"=>"record_pattern_cases"}.freeze,
+        {"script"=>"corpus", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"rust_domains"}.freeze,
+        {"script"=>"corpus", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"regen_order"}.freeze,
+        {"script"=>"corpus", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"corpus_rust_coverage"}.freeze,
+        {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_constructs"}.freeze,
+        {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_duplicates"}.freeze,
+        {"script"=>"query_ir", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"ir_impact"}.freeze,
+        {"script"=>"hecks_query_ir_mcp", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"serve_query_ir_mcp"}.freeze,
+        {"script"=>"present", "section"=>"Codebase", "aggregate"=>"CorpusRun", "verb"=>"present"}.freeze,
+        {"script"=>"release", "section"=>"Codebase", "aggregate"=>"PublishingRun", "verb"=>"publish", "note"=>"without --confirm, the old --dry-run"}.freeze,
+        {"script"=>"release_gem", "section"=>"Codebase", "aggregate"=>"PublishingRun", "verb"=>"publish_gem"}.freeze,
+        {"script"=>"(new)", "section"=>"Codebase", "aggregate"=>"GateRun", "verb"=>"gate"}.freeze,
+        {"script"=>"qa_tick", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"tick"}.freeze,
+        {"script"=>"qa_sweep", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"run", "passes"=>"--all --seeds N --steps N --adversarial F --role-draw F --dry-run F --self-consistency BOOL --modes a,b --persistence-parity --no-parity"}.freeze,
+        {"script"=>"qa_sweep", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"release"}.freeze,
+        {"script"=>"qa_pr_check", "section"=>"QualityControl", "aggregate"=>"Clearance", "verb"=>"check_pull_requests"}.freeze,
+        {"script"=>"qa_open_pr", "section"=>"QualityControl", "aggregate"=>"Patch", "verb"=>"open"}.freeze,
+        {"script"=>"qa_open_pr", "section"=>"QualityControl", "aggregate"=>"Improvement", "verb"=>"open"}.freeze,
+        {"script"=>"qa_log_bug", "section"=>"QualityControl", "aggregate"=>"Bug", "verb"=>"log"}.freeze,
+        {"script"=>"qa_seed_angles", "section"=>"QualityControl", "aggregate"=>"Angle", "verb"=>"seed"}.freeze,
+        {"script"=>"qa_seed_targets", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"seed"}.freeze,
+        {"script"=>"qa_generated_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"check_generated_domains", "passes"=>"--domains 3 --start N --forms a,b --seeds 5 --steps 25 --adversarial 0.3 --rust --shrink-budget 200 --domain-shrink-budget 40 --promote dir --name N --from-dials --blueprint F --source F"}.freeze,
+        {"script"=>"qa_mine_combinations", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"mine_combinations", "passes"=>"--candidates 3 --rust --seeds 5 --steps 25 --adversarial 0.3 --repair-rounds 1 --agent CMD --from DIR --against PATH --brief"}.freeze,
+        {"script"=>"qa_domain_novelty", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"judge_novelty", "passes"=>"--against PATH …"}.freeze,
+        {"script"=>"qa_discover_external_domains", "section"=>"QualityControl", "aggregate"=>"Target", "verb"=>"discover_external_domains", "passes"=>"--projects-dir ~/Projects --max-depth 3 --known-path PATH …"}.freeze,
+        {"script"=>"qa_postgres_migrate", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"migrate_ledger_from_heki", "passes"=>"[aggregate …] --force", "note"=>"a dry run without --force"}.freeze,
+        {"script"=>"qa_postgres_role", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"create_ledger_role"}.freeze,
+        {"script"=>"qa_concurrency_racer", "section"=>"QualityControl", "aggregate"=>"Sweep", "verb"=>"race", "note"=>"not user-facing; ProcessPool starts it"}.freeze
+      ].freeze,
       "RustReservedWord" => [
         {"word"=>"as"}.freeze,
         {"word"=>"break"}.freeze,

data/lib/hecks.rb

@@ -34,6 +34,7 @@ require_relative "hecks/doors/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/framework"
 require_relative "hecks/vendoring"
 require_relative "hecks/embryonaut_bluebook"