hecks 3.2.1 → 3.4.0

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -21,6 +21,8 @@ Hecks.bluebook "SME" do
     attribute :thing_findings,  list_of(ThingFinding)
     attribute :action_findings, list_of(ActionFinding)
     attribute :rule_findings,   list_of(RuleFinding)
+    attribute :field_findings,      list_of(FieldFinding)
+    attribute :transition_findings, list_of(TransitionFinding)
 
     # Held as counts because a rule cannot look inside a list: `Conclude` needs to know that at least
     # one thing and one action were accepted, and each acceptance adds one here (see the policies).
@@ -92,6 +94,17 @@ Hecks.bluebook "SME" do
       attribute :value, Boolean
     end
 
+    # A list the expert gave in a breath, comma separated: the values a field may take, or the
+    # fields an action needs to be told. Absent when the expert gave none.
+    value_object "Listing" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Who may do an action, in the expert's words ("a maintainer", "QA engineer").
+    value_object "Actor" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     # A thing the domain keeps track of, and the field that identifies one: an aggregate to be.
     entity "ThingFinding" do
       description "A thing the expert described, proposed as an aggregate, with the field that identifies one."
@@ -136,6 +149,8 @@ Hecks.bluebook "SME" do
       attribute :thing,   Name
       attribute :event,   Name
       attribute :creates, Creates, optional: true
+      attribute :takes,   Listing, optional: true
+      attribute :by,      Actor, optional: true
       attribute :source,  Source
 
       lifecycle :status, default: "proposed" do
@@ -192,6 +207,77 @@ Hecks.bluebook "SME" do
       end
     end
 
+    # Something the expert said a thing has, and the values it may take when they listed them: an
+    # attribute to be, with a closed set when the expert gave one.
+    entity "FieldFinding" do
+      description "A field the expert said a thing has, with the values it may take when they listed them."
+
+      identified_by :number
+
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :name,   Name
+      attribute :values, Listing, optional: true
+      attribute :source, Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptField" => "accepted", from: "proposed"
+        transition "RejectField" => "rejected", from: "proposed"
+      end
+
+      command "AcceptField", from: "proposed" do
+        goal "Establish that the field is real"
+
+        attribute :number, FindingNumber
+
+        emits "FieldAccepted"
+      end
+
+      command "RejectField", from: "proposed" do
+        goal "Set the proposed field aside"
+
+        attribute :number, FindingNumber
+
+        emits "FieldRejected"
+      end
+    end
+
+    # The state a thing is in after an action, and the state it had to be in before: one step of a
+    # lifecycle to be. The step an action that creates the thing makes names the state it starts in.
+    entity "TransitionFinding" do
+      description "A change of state an action makes to a thing, and the state it must be in before."
+
+      identified_by :number
+
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :action, Name
+      attribute :to,     Name
+      attribute :from,   Name, optional: true
+      attribute :source, Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptTransition" => "accepted", from: "proposed"
+        transition "RejectTransition" => "rejected", from: "proposed"
+      end
+
+      command "AcceptTransition", from: "proposed" do
+        goal "Establish that the change of state is real"
+
+        attribute :number, FindingNumber
+
+        emits "TransitionAccepted"
+      end
+
+      command "RejectTransition", from: "proposed" do
+        goal "Set the proposed change of state aside"
+
+        attribute :number, FindingNumber
+
+        emits "TransitionRejected"
+      end
+    end
+
     lifecycle :status, default: "planned" do
       transition "Begin"    => "underway",  from: "planned"
       transition "Conclude" => "concluded", from: "underway"
@@ -257,16 +343,57 @@ Hecks.bluebook "SME" do
       attribute :thing,   Name
       attribute :event,   Name
       attribute :creates, Creates, optional: true
+      attribute :takes,   Listing, optional: true
+      attribute :by,      Actor, optional: true
       attribute :source,  Source
 
       given("findings are proposed only while the interview is underway") { status == "underway" }
       given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
 
-      sets :action_findings, append: { number: :number, name: :name, thing: :thing, event: :event, creates: :creates, source: :source }
+      sets :action_findings, append: { number: :number, name: :name, thing: :thing, event: :event, creates: :creates,
+                                       takes: :takes, by: :by, source: :source }
 
       emits "ActionProposed"
     end
 
+    command "ProposeField" do
+      goal "Propose a field the expert said a thing has, and the values it may take"
+
+      reference_to Interview
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :name,   Name
+      attribute :values, Listing, optional: true
+      attribute :source, Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :field_findings, append: { number: :number, thing: :thing, name: :name, values: :values, source: :source }
+
+      emits "FieldProposed"
+    end
+
+    command "ProposeTransition" do
+      goal "Propose the change of state an action makes to a thing"
+
+      reference_to Interview
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :action, Name
+      attribute :to,     Name
+      attribute :from,   Name, optional: true
+      attribute :source, Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :transition_findings, append: { number: :number, thing: :thing, action: :action, to: :to, from: :from,
+                                           source: :source }
+
+      emits "TransitionProposed"
+    end
+
     command "ProposeRule" do
       goal "Keep a rule in the expert's words"
 

data/lib/hecks/tools/gate.rb

@@ -25,7 +25,7 @@ module Hecks
       # @param root [String] the checkout the checks run in
       # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
       def main(argv, root: Tools::ROOT, **)
-        stages = YAML.load_file(STAGES_FILE)
+        stages = YAML.load_file(STAGES_FILE, aliases: true)
         return list(stages) if argv == ["--list"]
 
         name = argv.find { |arg| !arg.include?("=") && !arg.start_with?("--") }

data/lib/hecks/tools/rust_comment_style.rb

@@ -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/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.1".freeze
+  VERSION = "3.4.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -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,